From 219bebd5a2b20ee367469595470a9c742b4d63bd Mon Sep 17 00:00:00 2001 From: Lacky1234union Date: Thu, 15 Oct 2026 19:03:50 +0300 Subject: [PATCH 1/4] =?UTF-8?q?feat(bot):=20=D0=B4=D0=BE=D1=81=D1=82=D1=83?= =?UTF-8?q?=D0=BF=20=D0=BF=D0=BE=20QR-=D0=BF=D1=80=D0=B8=D0=B3=D0=BB=D0=B0?= =?UTF-8?q?=D1=88=D0=B5=D0=BD=D0=B8=D1=8F=D0=BC,=20=D1=80=D0=B0=D0=B7?= =?UTF-8?q?=D0=B4=D0=B5=D0=BB=20=C2=AB=D0=A3=D1=87=D0=B0=D1=81=D1=82=D0=BD?= =?UTF-8?q?=D0=B8=D0=BA=D0=B8=C2=BB,=20=D0=BE=D1=82=D0=B7=D1=8B=D0=B2=20?= =?UTF-8?q?=D0=B4=D0=BE=D1=81=D1=82=D1=83=D0=BF=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AccessService: одноразовые приглашения (128 бит, в БД только sha256, TTL 24 ч), атомарный захват приглашения (условный UPDATE — из двух сканов одного QR проходит один), антиперебор (> 5 неудач в час — молчание), отзыв (черновик и FSM удаляются), повторное приглашение - ADMIN_IDS заводятся в БД при старте; дальше — только по приглашению - AccessMiddleware: участники из БД (+ last_seen раз в 5 мин), новичкам — только /start <токен> - «👥 Участники» для админов: список, QR (segno) + ссылка, отзыв с подтверждением - один ответ на неверный/истёкший/использованный токен — без подсказок Refs #25 Co-Authored-By: Claude Opus 5.5 --- app/access/__init__.py | 0 app/access/qr.py | 13 +++ app/access/service.py | 174 ++++++++++++++++++++++++++++++++++ app/bot/middlewares/access.py | 40 +++++--- app/bot/routers/common.py | 41 ++++---- app/bot/routers/members.py | 111 ++++++++++++++++++++++ app/config.py | 3 + app/main.py | 23 +++-- app/texts.py | 16 ++++ config/texts.yaml | 18 ++++ tests/access/__init__.py | 0 tests/access/test_service.py | 138 +++++++++++++++++++++++++++ tests/bot/test_common.py | 8 +- tests/bot/test_members.py | 94 ++++++++++++++++++ tests/conftest.py | 8 ++ tests/fakes.py | 12 ++- 16 files changed, 655 insertions(+), 44 deletions(-) create mode 100644 app/access/__init__.py create mode 100644 app/access/qr.py create mode 100644 app/access/service.py create mode 100644 app/bot/routers/members.py create mode 100644 tests/access/__init__.py create mode 100644 tests/access/test_service.py create mode 100644 tests/bot/test_members.py diff --git a/app/access/__init__.py b/app/access/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/app/access/qr.py b/app/access/qr.py new file mode 100644 index 0000000..b06e1ae --- /dev/null +++ b/app/access/qr.py @@ -0,0 +1,13 @@ +import io + +import segno + + +def invite_link(bot_username: str, token: str) -> str: + return f"https://t.me/{bot_username}?start={token}" + + +def qr_png(data: str) -> bytes: + buf = io.BytesIO() + segno.make(data, error="m").save(buf, kind="png", scale=10, border=2) + return buf.getvalue() diff --git a/app/access/service.py b/app/access/service.py new file mode 100644 index 0000000..50a8285 --- /dev/null +++ b/app/access/service.py @@ -0,0 +1,174 @@ +"""Invites, members and revocation (SPEC §3.1, ADR-011).""" + +import hashlib +import secrets +from collections.abc import Callable +from dataclasses import dataclass +from datetime import UTC, datetime, timedelta +from enum import StrEnum +from typing import Any, cast + +from sqlalchemy import CursorResult, delete, func, select, update + +from app.config import AccessSettings +from app.db.models import AccessAttempt, Draft, FsmState, Invite, Role, User, utcnow +from app.db.session import SessionMaker + +LAST_SEEN_EVERY = timedelta(minutes=5) +ATTEMPT_WINDOW = timedelta(hours=1) + + +class RedeemStatus(StrEnum): + OK = "ok" + ALREADY_MEMBER = "already_member" + REJECTED = "rejected" # unknown, used or expired — one answer, no hints which tokens existed + THROTTLED = "throttled" + + +@dataclass(frozen=True) +class TgUser: + tg_id: int + full_name: str + username: str | None = None + + +@dataclass(frozen=True) +class CreatedInvite: + token: str + expires_at: datetime + + +def hash_token(token: str) -> str: + return hashlib.sha256(token.encode()).hexdigest() + + +class AccessService: + def __init__(self, sessions: SessionMaker, settings: AccessSettings, clock: Callable[[], datetime] = utcnow): + self._sessions = sessions + self._settings = settings + self._clock = clock + + async def bootstrap_admins(self) -> None: + """ADMIN_IDS become active admins in the DB; everybody else gets in only by invite (SPEC A-8).""" + async with self._sessions.begin() as s: + for tg_id in self._settings.admin_ids: + user = await s.get(User, tg_id) + if user is None: + s.add(User(tg_id=tg_id, full_name=f"admin {tg_id}", role=Role.ADMIN, joined_at=self._clock())) + else: + user.role, user.is_active = Role.ADMIN, True + + async def get_member(self, tg_id: int) -> User | None: + async with self._sessions() as s: + user = await s.get(User, tg_id) + return user if user is not None and user.is_active else None + + async def touch(self, member: User, seen: TgUser) -> None: + """Refresh name and last-seen, at most every few minutes — not a write per update.""" + now = self._clock() + last = member.last_seen_at + if ( + last is not None + and now - _aware(last) < LAST_SEEN_EVERY + and (member.full_name, member.username) == (seen.full_name, seen.username) + ): + return + async with self._sessions.begin() as s: + await s.execute( + update(User) + .where(User.tg_id == member.tg_id) + .values(last_seen_at=now, full_name=seen.full_name, username=seen.username) + ) + + async def create_invite(self, admin_id: int) -> CreatedInvite: + token = secrets.token_urlsafe(16) # 128 bits, 22 chars of [A-Za-z0-9_-]: fits the 64-char deep link payload + expires_at = self._clock() + timedelta(hours=self._settings.invite_ttl_hours) + async with self._sessions.begin() as s: + s.add( + Invite( + token_hash=hash_token(token), created_by=admin_id, created_at=self._clock(), expires_at=expires_at + ) + ) + return CreatedInvite(token=token, expires_at=expires_at) + + async def redeem(self, token: str, who: TgUser) -> RedeemStatus: + now = self._clock() + try: + async with self._sessions.begin() as s: + existing = await s.get(User, who.tg_id) + if existing is not None and existing.is_active: + return RedeemStatus.ALREADY_MEMBER + failed = await s.scalar( + select(func.count()) + .select_from(AccessAttempt) + .where( + AccessAttempt.tg_id == who.tg_id, + AccessAttempt.ok.is_(False), + AccessAttempt.at > now - ATTEMPT_WINDOW, + ) + ) + if (failed or 0) >= self._settings.max_failed_attempts: + return RedeemStatus.THROTTLED + + invite = await s.scalar(select(Invite).where(Invite.token_hash == hash_token(token))) + if invite is None or invite.used_by is not None or _aware(invite.expires_at) <= now: + raise _Rejected + + if existing is None: + s.add( + User( + tg_id=who.tg_id, + full_name=who.full_name, + username=who.username, + role=Role.MEMBER, + invited_by=invite.created_by, + joined_at=now, + last_seen_at=now, + ) + ) + else: # revoked earlier, invited again + existing.is_active, existing.role, existing.invited_by = True, Role.MEMBER, invite.created_by + existing.full_name, existing.username, existing.last_seen_at = who.full_name, who.username, now + await s.flush() # the user row must exist before invites.used_by points at it + + # Claim atomically: of two people scanning the same QR only one UPDATE matches the row, + # the loser's transaction (with its freshly created user) is rolled back. + result = await s.execute( + update(Invite) + .where(Invite.id == invite.id, Invite.used_by.is_(None)) + .values(used_by=who.tg_id, used_at=now) + ) + if cast(CursorResult[Any], result).rowcount != 1: + raise _Rejected + s.add(AccessAttempt(tg_id=who.tg_id, at=now, ok=True)) + except _Rejected: + async with self._sessions.begin() as s: + s.add(AccessAttempt(tg_id=who.tg_id, at=now, ok=False)) + return RedeemStatus.REJECTED + return RedeemStatus.OK + + async def list_members(self) -> list[User]: + async with self._sessions() as s: + rows = await s.scalars(select(User).where(User.is_active.is_(True)).order_by(User.role, User.joined_at)) + return list(rows) + + async def revoke(self, tg_id: int) -> bool: + """Cut a member off at once: their updates are ignored from now on, draft and dialog state are dropped.""" + async with self._sessions.begin() as s: + user = await s.get(User, tg_id) + if user is None or not user.is_active or user.role is Role.ADMIN: + return False + user.is_active = False + await s.execute(delete(Draft).where(Draft.user_id == tg_id)) + # FSM keys are "bot:chat:user:…"; in a private chat chat == user + await s.execute(delete(FsmState).where(FsmState.key.like(f"%:{tg_id}:{tg_id}:%"))) + return True + + +class _Rejected(Exception): + pass + + +def _aware(value: datetime) -> datetime: + # SQLite hands back naive datetimes even for timezone=True columns; everything we store is UTC. + return value if value.tzinfo is not None else value.replace(tzinfo=UTC) diff --git a/app/bot/middlewares/access.py b/app/bot/middlewares/access.py index 64ecfbb..363c773 100644 --- a/app/bot/middlewares/access.py +++ b/app/bot/middlewares/access.py @@ -1,6 +1,7 @@ -"""Access gate on every update — messages and button presses alike (SPEC A-5). +"""Access gate on every update — messages and button presses alike (SPEC A-5, ADR-011). -Until invites land (#25) the only members are the bootstrap admins from `ADMIN_IDS`. +Members (active users in the DB) pass with `member` injected into handler data. Outsiders pass only with +`/start ` — the invite deep link; everything else gets one "invite only" reply a day, then silence. """ import time @@ -8,18 +9,28 @@ from collections.abc import Awaitable, Callable from typing import Any from aiogram import BaseMiddleware -from aiogram.types import CallbackQuery, Message, TelegramObject +from aiogram.types import CallbackQuery, Message, TelegramObject, User +from app.access.service import AccessService, TgUser from app.texts import Texts -IsMember = Callable[[int], Awaitable[bool]] - NO_ACCESS_REPLY_EVERY = 24 * 3600.0 +def tg_user(user: User) -> TgUser: + return TgUser(tg_id=user.id, full_name=user.full_name, username=user.username) + + +def is_invite_link(event: TelegramObject) -> bool: + if not isinstance(event, Message) or not event.text: + return False + parts = event.text.split(maxsplit=1) + return len(parts) == 2 and parts[0].split("@")[0] == "/start" + + class AccessMiddleware(BaseMiddleware): - def __init__(self, is_member: IsMember, texts: Texts, clock: Callable[[], float] = time.monotonic) -> None: - self._is_member = is_member + def __init__(self, access: AccessService, texts: Texts, clock: Callable[[], float] = time.monotonic) -> None: + self._access = access self._texts = texts self._clock = clock # tg_id -> when we last told this outsider "invite only"; answering every message would let them spam us. @@ -31,11 +42,18 @@ class AccessMiddleware(BaseMiddleware): event: TelegramObject, data: dict[str, Any], ) -> Any: - user = data.get("event_from_user") - if user is not None and await self._is_member(user.id): + user: User | None = data.get("event_from_user") + if user is None: + return None + member = await self._access.get_member(user.id) + if member is not None: + await self._access.touch(member, tg_user(user)) + data["member"] = member return await handler(event, data) - if user is not None: - await self._refuse(event, user.id) + if is_invite_link(event): + data["member"] = None + return await handler(event, data) + await self._refuse(event, user.id) return None async def _refuse(self, event: TelegramObject, tg_id: int) -> None: diff --git a/app/bot/routers/common.py b/app/bot/routers/common.py index 9ce708c..aa960d5 100644 --- a/app/bot/routers/common.py +++ b/app/bot/routers/common.py @@ -1,15 +1,18 @@ -"""/start, /help, /menu, main menu buttons and in-section navigation.""" +"""/start (incl. invite deep links), /help, /menu, main menu buttons and in-section navigation.""" from aiogram import F, Router -from aiogram.filters import Command, CommandStart +from aiogram.filters import Command, CommandObject, CommandStart from aiogram.fsm.context import FSMContext from aiogram.types import CallbackQuery, Message +from app.access.service import AccessService, RedeemStatus from app.bot.menu import Nav, NavAction, Section, main_menu, section_by_button, section_nav +from app.bot.middlewares.access import tg_user +from app.db.models import Role, User from app.texts import Texts -def build_router(texts: Texts, admin_ids: frozenset[int]) -> Router: +def build_router(texts: Texts, access: AccessService) -> Router: router = Router(name="common") sections = section_by_button(texts) section_text = { @@ -17,33 +20,39 @@ def build_router(texts: Texts, admin_ids: frozenset[int]) -> Router: Section.STATUS: texts.section.status, Section.LOGS: texts.section.logs, Section.ALERTS: texts.section.alerts, - Section.MEMBERS: texts.section.members, } - def is_admin(message: Message) -> bool: - return message.from_user is not None and message.from_user.id in admin_ids - @router.message(CommandStart()) - async def start(message: Message, state: FSMContext) -> None: + async def start(message: Message, command: CommandObject, state: FSMContext, member: User | None) -> None: + if member is None: + # Only an outsider with an invite token gets here (AccessMiddleware); a member's /start is a plain start + if message.from_user is None or not command.args: + return + status = await access.redeem(command.args, tg_user(message.from_user)) + if status is RedeemStatus.THROTTLED: + return # brute force: stay silent (SPEC A-6) + if status is RedeemStatus.REJECTED: + await message.answer(texts.start.invite_rejected) + return + member = await access.get_member(message.from_user.id) + if member is None: + return await state.clear() - await message.answer(texts.start.welcome, reply_markup=main_menu(texts, is_admin=is_admin(message))) + await message.answer(texts.start.welcome, reply_markup=main_menu(texts, is_admin=member.role is Role.ADMIN)) @router.message(Command("menu")) - async def menu(message: Message, state: FSMContext) -> None: + async def menu(message: Message, state: FSMContext, member: User) -> None: await state.clear() - await message.answer(texts.menu.placeholder, reply_markup=main_menu(texts, is_admin=is_admin(message))) + await message.answer(texts.menu.placeholder, reply_markup=main_menu(texts, is_admin=member.role is Role.ADMIN)) @router.message(Command("help")) async def help_(message: Message) -> None: await message.answer(texts.help.text) - @router.message(F.text.in_(sections)) + @router.message(F.text.in_({k for k, v in sections.items() if v is not Section.MEMBERS})) async def open_section(message: Message, state: FSMContext) -> None: - section = sections[message.text or ""] - if section is Section.MEMBERS and not is_admin(message): - return await state.clear() - await message.answer(section_text[section], reply_markup=section_nav(texts)) + await message.answer(section_text[sections[message.text or ""]], reply_markup=section_nav(texts)) @router.callback_query(Nav.filter()) async def navigate(query: CallbackQuery, callback_data: Nav, state: FSMContext) -> None: diff --git a/app/bot/routers/members.py b/app/bot/routers/members.py new file mode 100644 index 0000000..44f158b --- /dev/null +++ b/app/bot/routers/members.py @@ -0,0 +1,111 @@ +"""«👥 Участники» for admins: list, invite by QR, revoke access (SPEC A-1, A-7).""" + +from datetime import datetime +from enum import StrEnum + +from aiogram import Bot, F, Router +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.access.qr import invite_link, qr_png +from app.access.service import AccessService +from app.bot.menu import Nav, NavAction +from app.db.models import Role, User +from app.texts import Texts + + +class MembersAction(StrEnum): + INVITE = "inv" + ASK_REVOKE = "ask" + REVOKE = "rev" + LIST = "list" + + +class MembersCb(CallbackData, prefix="mem"): + action: MembersAction + tg_id: int = 0 + + +def _fmt(dt: datetime | None, never: str) -> str: + return dt.strftime("%d.%m %H:%M") if dt else never + + +def render_members(texts: Texts, members: list[User]) -> tuple[str, InlineKeyboardMarkup]: + t = texts.members + lines = [t.title.format(count=len(members)), ""] + for m in members: + lines.append( + t.line.format( + icon="👑" if m.role is Role.ADMIN else "👤", + name=m.full_name, + username=f" @{m.username}" if m.username else "", + joined=_fmt(m.joined_at, t.never), + seen=_fmt(m.last_seen_at, t.never), + ) + ) + kb = InlineKeyboardBuilder() + kb.button(text=t.invite, callback_data=MembersCb(action=MembersAction.INVITE)) + for m in members: + if m.role is not Role.ADMIN: + kb.button( + text=t.revoke.format(name=m.full_name), + callback_data=MembersCb(action=MembersAction.ASK_REVOKE, tg_id=m.tg_id), + ) + kb.button(text=texts.menu.back, callback_data=Nav(action=NavAction.BACK)) + kb.adjust(1) + return "\n".join(lines), kb.as_markup() + + +def build_router(texts: Texts, access: AccessService) -> Router: + router = Router(name="members") + t = texts.members + # Every handler here is admin-only; a member who somehow has the button (e.g. was demoted) gets nothing. + + def is_admin(member: User | None) -> bool: + return member is not None and member.role is Role.ADMIN + + @router.message(F.text == texts.menu.members) + async def open_members(message: Message, state: FSMContext, member: User) -> None: + if not is_admin(member): + return + await state.clear() + text, kb = render_members(texts, await access.list_members()) + await message.answer(text, reply_markup=kb) + + @router.callback_query(MembersCb.filter()) + async def on_action(query: CallbackQuery, callback_data: MembersCb, bot: Bot, member: User) -> None: + if not is_admin(member) or not isinstance(query.message, Message): + await query.answer() + return + msg = query.message + match callback_data.action: + case MembersAction.INVITE: + invite = await access.create_invite(member.tg_id) + me = await bot.me() + link = invite_link(me.username or "", invite.token) + caption = t.invite_caption.format(link=link, expires=invite.expires_at.strftime("%d.%m %H:%M")) + await msg.answer_photo(BufferedInputFile(qr_png(link), "invite.png"), caption=caption) + case MembersAction.ASK_REVOKE: + target = await access.get_member(callback_data.tg_id) + name = target.full_name if target else str(callback_data.tg_id) + kb = InlineKeyboardBuilder() + kb.button( + text=t.confirm_yes, callback_data=MembersCb(action=MembersAction.REVOKE, tg_id=callback_data.tg_id) + ) + kb.button(text=t.confirm_no, callback_data=MembersCb(action=MembersAction.LIST)) + await msg.edit_text(t.confirm.format(name=name), reply_markup=kb.as_markup()) + case MembersAction.REVOKE: + target = await access.get_member(callback_data.tg_id) + name = target.full_name if target else str(callback_data.tg_id) + ok = await access.revoke(callback_data.tg_id) + text, kb_markup = render_members(texts, await access.list_members()) + note = t.revoked.format(name=name) if ok else t.not_revoked + await msg.edit_text(f"{note}\n\n{text}", reply_markup=kb_markup) + case MembersAction.LIST: + text, kb_markup = render_members(texts, await access.list_members()) + await msg.edit_text(text, reply_markup=kb_markup) + await query.answer() + + return router diff --git a/app/config.py b/app/config.py index aaac296..e0c6ecc 100644 --- a/app/config.py +++ b/app/config.py @@ -20,6 +20,9 @@ class AccessSettings(BaseSettings): # Bootstrap admins (SPEC A-8). Comma-separated in the env: ADMIN_IDS=1,2 admin_ids: Annotated[frozenset[int], NoDecode] = frozenset() + invite_ttl_hours: float = Field(default=24.0, gt=0) + # More failed /start per hour than this — silence (SPEC A-6) + max_failed_attempts: int = Field(default=5, ge=1) @field_validator("admin_ids", mode="before") @classmethod diff --git a/app/main.py b/app/main.py index 097eefb..9b1ed17 100644 --- a/app/main.py +++ b/app/main.py @@ -7,9 +7,10 @@ import logging from aiogram import Bot, Dispatcher 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.common import build_router +from app.bot.routers import common, members from app.config import Settings from app.db.maintenance import cleanup_loop from app.db.migrate import upgrade @@ -21,18 +22,14 @@ from app.texts import Texts, load_texts log = logging.getLogger("tgit") -def build_dispatcher(settings: Settings, texts: Texts, sessions: SessionMaker) -> Dispatcher: - admin_ids = settings.access.admin_ids - - async def is_member(tg_id: int) -> bool: - return tg_id in admin_ids - +def build_dispatcher(texts: Texts, sessions: SessionMaker, access: AccessService) -> Dispatcher: dp = Dispatcher(storage=make_storage(sessions)) - access = AccessMiddleware(is_member, texts) + gate = AccessMiddleware(access, texts) # Outer middleware: runs before filters, so nothing — not even a stale button — reaches a handler unchecked. - dp.message.outer_middleware(access) - dp.callback_query.outer_middleware(access) - dp.include_router(build_router(texts, admin_ids)) + dp.message.outer_middleware(gate) + dp.callback_query.outer_middleware(gate) + dp.include_router(members.build_router(texts, access)) + dp.include_router(common.build_router(texts, access)) return dp @@ -41,7 +38,9 @@ async def run(settings: Settings) -> None: engine = make_engine(settings.database.url) await upgrade(engine) sessions = make_sessionmaker(engine) - dp = build_dispatcher(settings, texts, sessions) + access = AccessService(sessions, settings.access) + await access.bootstrap_admins() + dp = build_dispatcher(texts, sessions, access) rt = settings.runtime background = [ asyncio.create_task(heartbeat(rt.heartbeat_file, rt.heartbeat_interval)), diff --git a/app/texts.py b/app/texts.py index 5308771..2494222 100644 --- a/app/texts.py +++ b/app/texts.py @@ -24,6 +24,7 @@ class MenuTexts(_Strict): class StartTexts(_Strict): welcome: str no_access: str + invite_rejected: str class HelpTexts(_Strict): @@ -39,11 +40,26 @@ class SectionTexts(_Strict): cancelled: str +class MembersTexts(_Strict): + title: str + line: str + never: str + invite: str + revoke: str + confirm: str + confirm_yes: str + confirm_no: str + revoked: str + not_revoked: str + invite_caption: str + + class Texts(_Strict): menu: MenuTexts start: StartTexts help: HelpTexts section: SectionTexts + members: MembersTexts def load_texts(config_dir: Path) -> Texts: diff --git a/config/texts.yaml b/config/texts.yaml index becd9e2..96984b1 100644 --- a/config/texts.yaml +++ b/config/texts.yaml @@ -19,6 +19,7 @@ start: 📜 Логи — хвост, свой grep или вопрос агенту 🚨 Алерты — падения, перегрузка, список no_access: "Доступ к боту — только по приглашению. Попросите QR-код у администратора." + invite_rejected: "Приглашение недействительно: истекло, уже использовано или ссылка неверная. Попросите новое у администратора." help: text: |- @@ -34,3 +35,20 @@ section: alerts: "🚨 Алерты\n\nРаздел в разработке." members: "👥 Участники\n\nРаздел в разработке." cancelled: "Отменено. Главное меню — кнопками внизу." + +members: + title: "👥 Участники: {count}" + line: "{icon} {name}{username} · с {joined} · был(а) {seen}" + never: "—" + invite: "➕ Пригласить" + revoke: "🚫 {name}" + confirm: "Отозвать доступ у {name}? Его черновик удалится, кнопки перестанут работать." + confirm_yes: "Да, отозвать" + confirm_no: "Нет" + revoked: "Доступ отозван: {name}." + not_revoked: "Нельзя отозвать: администратор или уже без доступа." + invite_caption: |- + Приглашение в tgit — отсканируйте QR или откройте ссылку: + {link} + + Одноразовое, действует до {expires} UTC. diff --git a/tests/access/__init__.py b/tests/access/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/access/test_service.py b/tests/access/test_service.py new file mode 100644 index 0000000..c2f38ae --- /dev/null +++ b/tests/access/test_service.py @@ -0,0 +1,138 @@ +from datetime import UTC, datetime, timedelta + +import pytest +from sqlalchemy import select + +from app.access.service import AccessService, RedeemStatus, TgUser, hash_token +from app.config import AccessSettings +from app.db.models import Draft, FsmState, Invite, Role, User +from app.db.session import SessionMaker + +ADMIN = 1 +NEWBIE = TgUser(tg_id=500, full_name="Новичок", username="newbie") + + +class Clock: + def __init__(self) -> None: + self.now = datetime(2026, 10, 15, 12, 0, tzinfo=UTC) + + def __call__(self) -> datetime: + return self.now + + +@pytest.fixture +def clock() -> Clock: + return Clock() + + +@pytest.fixture +async def svc(sessions: SessionMaker, clock: Clock) -> AccessService: + service = AccessService(sessions, AccessSettings(admin_ids=frozenset({ADMIN}), invite_ttl_hours=24), clock=clock) + await service.bootstrap_admins() + return service + + +async def test_bootstrap_is_idempotent_and_restores_admin(svc: AccessService, sessions: SessionMaker) -> None: + async with sessions.begin() as s: + admin = await s.get(User, ADMIN) + assert admin is not None + admin.is_active, admin.role = False, Role.MEMBER + await svc.bootstrap_admins() + await svc.bootstrap_admins() + + member = await svc.get_member(ADMIN) + assert member is not None and member.role is Role.ADMIN + + +async def test_invite_stores_only_hash(svc: AccessService, sessions: SessionMaker, clock: Clock) -> None: + invite = await svc.create_invite(ADMIN) + + assert len(invite.token) == 22 and invite.token.replace("-", "").replace("_", "").isalnum() + assert invite.expires_at == clock.now + timedelta(hours=24) + async with sessions() as s: + stored = await s.scalar(select(Invite)) + assert stored is not None and stored.token_hash == hash_token(invite.token) != invite.token + + +async def test_redeem_once_then_rejected_for_others(svc: AccessService, sessions: SessionMaker) -> None: + invite = await svc.create_invite(ADMIN) + + assert await svc.redeem(invite.token, NEWBIE) is RedeemStatus.OK + assert await svc.redeem(invite.token, NEWBIE) is RedeemStatus.ALREADY_MEMBER + assert await svc.redeem(invite.token, TgUser(tg_id=501, full_name="x")) is RedeemStatus.REJECTED + + member = await svc.get_member(NEWBIE.tg_id) + assert member is not None and member.role is Role.MEMBER and member.invited_by == ADMIN + async with sessions() as s: + stored = await s.scalar(select(Invite)) + assert stored is not None and stored.used_by == NEWBIE.tg_id + assert await s.get(User, 501) is None # the loser's user row was rolled back + + +async def test_expired_invite_rejected(svc: AccessService, clock: Clock) -> None: + invite = await svc.create_invite(ADMIN) + clock.now += timedelta(hours=24, seconds=1) + + assert await svc.redeem(invite.token, NEWBIE) is RedeemStatus.REJECTED + assert await svc.get_member(NEWBIE.tg_id) is None + + +async def test_brute_force_is_throttled_even_with_a_valid_token(svc: AccessService, clock: Clock) -> None: + for i in range(5): + assert await svc.redeem(f"guess-{i}", NEWBIE) is RedeemStatus.REJECTED + invite = await svc.create_invite(ADMIN) + + assert await svc.redeem(invite.token, NEWBIE) is RedeemStatus.THROTTLED + clock.now += timedelta(hours=1, seconds=1) + assert await svc.redeem(invite.token, NEWBIE) is RedeemStatus.OK + + +async def test_revoke_drops_access_draft_and_dialog(svc: AccessService, sessions: SessionMaker, clock: Clock) -> None: + await svc.redeem((await svc.create_invite(ADMIN)).token, NEWBIE) + async with sessions.begin() as s: + s.add(Draft(user_id=NEWBIE.tg_id, base_sha="0" * 40, expires_at=clock.now + timedelta(hours=1))) + s.add(FsmState(key=f"42:{NEWBIE.tg_id}:{NEWBIE.tg_id}:::default", state="x", data={})) + s.add(FsmState(key=f"42:{ADMIN}:{ADMIN}:::default", state="y", data={})) + + assert await svc.revoke(NEWBIE.tg_id) + + assert await svc.get_member(NEWBIE.tg_id) is None + async with sessions() as s: + assert await s.scalar(select(Draft)) is None + assert [r.key for r in await s.scalars(select(FsmState))] == [f"42:{ADMIN}:{ADMIN}:::default"] + + +async def test_admin_cannot_be_revoked_and_unknown_is_noop(svc: AccessService) -> None: + assert not await svc.revoke(ADMIN) + assert not await svc.revoke(999) + + +async def test_revoked_member_can_be_invited_again(svc: AccessService) -> None: + await svc.redeem((await svc.create_invite(ADMIN)).token, NEWBIE) + await svc.revoke(NEWBIE.tg_id) + + assert await svc.redeem((await svc.create_invite(ADMIN)).token, NEWBIE) is RedeemStatus.OK + assert await svc.get_member(NEWBIE.tg_id) is not None + + +async def test_members_listed_admins_first(svc: AccessService) -> None: + await svc.redeem((await svc.create_invite(ADMIN)).token, NEWBIE) + + assert [m.tg_id for m in await svc.list_members()] == [ADMIN, NEWBIE.tg_id] + + +async def test_touch_is_throttled_but_tracks_renames(svc: AccessService, clock: Clock) -> None: + member = await svc.get_member(ADMIN) + assert member is not None + await svc.touch(member, TgUser(ADMIN, "Админ", "boss")) + first = await svc.get_member(ADMIN) + assert first is not None and first.full_name == "Админ" and first.last_seen_at is not None + + clock.now += timedelta(minutes=1) + await svc.touch(first, TgUser(ADMIN, "Админ", "boss")) + same = await svc.get_member(ADMIN) + assert same is not None and same.last_seen_at == first.last_seen_at # no write within 5 minutes + + await svc.touch(same, TgUser(ADMIN, "Новое имя", "boss")) + renamed = await svc.get_member(ADMIN) + assert renamed is not None and renamed.full_name == "Новое имя" diff --git a/tests/bot/test_common.py b/tests/bot/test_common.py index 0be65f0..2ca8df1 100644 --- a/tests/bot/test_common.py +++ b/tests/bot/test_common.py @@ -2,8 +2,8 @@ import pytest from aiogram.methods import AnswerCallbackQuery, EditMessageText, SendMessage from aiogram.types import InlineKeyboardMarkup, ReplyKeyboardMarkup +from app.access.service import AccessService from app.bot.menu import Nav, NavAction -from app.config import Settings from app.db.session import SessionMaker from app.main import build_dispatcher from app.texts import Texts @@ -12,8 +12,8 @@ from tests.fakes import TgClient @pytest.fixture -def tg(settings: Settings, texts: Texts, sessions: SessionMaker) -> TgClient: - return TgClient(build_dispatcher(settings, texts, sessions)) +def tg(texts: Texts, sessions: SessionMaker, access: AccessService) -> TgClient: + return TgClient(build_dispatcher(texts, sessions, access)) def buttons(markup: ReplyKeyboardMarkup) -> list[str]: @@ -45,7 +45,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", "members"]) +@pytest.mark.parametrize("section", ["commit", "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 new file mode 100644 index 0000000..5e5cfd5 --- /dev/null +++ b/tests/bot/test_members.py @@ -0,0 +1,94 @@ +import re + +import pytest +from aiogram.methods import AnswerCallbackQuery, EditMessageText, SendMessage, SendPhoto +from aiogram.types import ReplyKeyboardMarkup + +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.texts import Texts +from tests.conftest import ADMIN +from tests.fakes import TgClient + +NEWBIE = 3003 + + +@pytest.fixture +def tg(texts: Texts, sessions: SessionMaker, access: AccessService) -> TgClient: + return TgClient(build_dispatcher(texts, sessions, access)) + + +async def invite_token(tg: TgClient) -> str: + await tg.press(ADMIN, MembersCb(action=MembersAction.INVITE).pack()) + [photo] = tg.session.sent(SendPhoto) + match = re.search(r"https://t\.me/tgit_test_bot\?start=([A-Za-z0-9_-]+)", photo.caption or "") + assert match, photo.caption + tg.session.requests.clear() + return match.group(1) + + +async def test_admin_sees_members_list(tg: TgClient, texts: Texts) -> None: + await tg.send(ADMIN, texts.menu.members) + + [reply] = tg.session.sent(SendMessage) + assert reply.text.startswith(texts.members.title.format(count=1)) + + +async def test_full_invite_flow(tg: TgClient, texts: Texts) -> None: + token = await invite_token(tg) + + await tg.send(NEWBIE, f"/start {token}") + + [welcome] = tg.session.sent(SendMessage) + assert welcome.text == texts.start.welcome + assert isinstance(welcome.reply_markup, ReplyKeyboardMarkup) + labels = [b.text for row in welcome.reply_markup.keyboard for b in row] + assert texts.menu.members not in labels # a member, not an admin + + # the same QR again, from someone else + tg.session.requests.clear() + await tg.send(NEWBIE + 1, f"/start {token}") + assert [r.text for r in tg.session.sent(SendMessage)] == [texts.start.invite_rejected] + + +async def test_bad_token_rejected_and_bare_start_refused(tg: TgClient, texts: Texts) -> None: + await tg.send(NEWBIE, "/start nope") + await tg.send(NEWBIE + 1, "/start") + + assert [r.text for r in tg.session.sent(SendMessage)] == [texts.start.invite_rejected, texts.start.no_access] + + +async def test_revoke_with_confirmation_cuts_access(tg: TgClient, texts: Texts) -> None: + await tg.send(NEWBIE, f"/start {await invite_token(tg)}") + tg.session.requests.clear() + + await tg.press(ADMIN, MembersCb(action=MembersAction.ASK_REVOKE, tg_id=NEWBIE).pack()) + await tg.press(ADMIN, MembersCb(action=MembersAction.REVOKE, tg_id=NEWBIE).pack()) + + confirm, done = tg.session.sent(EditMessageText) + assert confirm.text == texts.members.confirm.format(name=f"u{NEWBIE}") + assert done.text.startswith(texts.members.revoked.format(name=f"u{NEWBIE}")) + + tg.session.requests.clear() + await tg.send(NEWBIE, texts.menu.commit) + assert [r.text for r in tg.session.sent(SendMessage)] == [texts.start.no_access] + + +async def test_member_cannot_use_admin_actions(tg: TgClient, texts: Texts) -> None: + await tg.send(NEWBIE, f"/start {await invite_token(tg)}") + tg.session.requests.clear() + + await tg.send(NEWBIE, texts.menu.members) + await tg.press(NEWBIE, MembersCb(action=MembersAction.INVITE).pack()) + + assert tg.session.sent(SendMessage) == [] and tg.session.sent(SendPhoto) == [] + assert len(tg.session.sent(AnswerCallbackQuery)) == 1 + + +async def test_cancel_revoke_returns_to_list(tg: TgClient, texts: Texts) -> None: + await tg.press(ADMIN, MembersCb(action=MembersAction.LIST).pack()) + + [edit] = tg.session.sent(EditMessageText) + assert edit.text.startswith(texts.members.title.format(count=1)) diff --git a/tests/conftest.py b/tests/conftest.py index 1d71aa1..856c49d 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -4,6 +4,7 @@ from pathlib import Path import pytest from sqlalchemy.ext.asyncio import AsyncEngine +from app.access.service import AccessService from app.config import AccessSettings, RuntimeSettings, Settings, TelegramSettings from app.db.migrate import upgrade from app.db.session import SessionMaker, make_engine, make_sessionmaker @@ -40,3 +41,10 @@ async def engine() -> AsyncIterator[AsyncEngine]: @pytest.fixture def sessions(engine: AsyncEngine) -> SessionMaker: return make_sessionmaker(engine) + + +@pytest.fixture +async def access(sessions: SessionMaker, settings: Settings) -> AccessService: + service = AccessService(sessions, settings.access) + await service.bootstrap_admins() + return service diff --git a/tests/fakes.py b/tests/fakes.py index 272e7ef..f03867d 100644 --- a/tests/fakes.py +++ b/tests/fakes.py @@ -7,7 +7,7 @@ from typing import Any from aiogram import Bot, Dispatcher from aiogram.client.session.base import BaseSession -from aiogram.methods import EditMessageText, SendMessage, TelegramMethod +from aiogram.methods import EditMessageText, GetMe, SendMessage, SendPhoto, TelegramMethod from aiogram.methods.base import TelegramType from aiogram.types import Chat, Message, Update, User @@ -27,6 +27,16 @@ class FakeSession(BaseSession): timeout: int | None = None, # noqa: ASYNC109 - signature fixed by aiogram BaseSession ) -> TelegramType: self.requests.append(method) + if isinstance(method, GetMe): + return User(id=42, is_bot=True, first_name="tgit", username="tgit_test_bot") # type: ignore[return-value] + if isinstance(method, SendPhoto): + chat = method.chat_id if isinstance(method.chat_id, int) else 0 + return Message( # type: ignore[return-value] + message_id=next(self._ids), + date=datetime.now(UTC), + chat=Chat(id=chat, type="private"), + caption=method.caption, + ) if isinstance(method, SendMessage | EditMessageText): chat_id = method.chat_id if isinstance(method.chat_id, int) else 0 return Message( # type: ignore[return-value] From dbb17bd77496847b774b02c2efab22beb4a5df71 Mon Sep 17 00:00:00 2001 From: Lacky1234union Date: Thu, 15 Oct 2026 19:10:30 +0300 Subject: [PATCH 2/4] =?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, карточка файла с последним коммитом, «👁 Показать» (
 или документом); в кнопках только индексы
- ключ для контейнера: GIT_SSH_KEY_B64 → временный файл 0600 (смонтированный файл хоста
  контейнерному uid не прочитать); volume /data для клона
- тесты на настоящем bare-репозитории во временной папке

Refs #8

Co-Authored-By: Claude Opus 5.5 
---
 .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 
 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"/{html.escape(path)}\n
{html.escape(text)}
", 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/` (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 "
привет\n
" 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()

From 614f8eafd5f9c0f07dd23ed50726184a8f84cd2f Mon Sep 17 00:00:00 2001
From: Lacky1234union 
Date: Thu, 15 Oct 2026 19:18:49 +0300
Subject: [PATCH 3/4] =?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=D1=81=D0=BE=D0=B7=D0=B4=D0=B0=D0=BD=D0=B8?=
 =?UTF-8?q?=D0=B5,=20=D0=B7=D0=B0=D0=BC=D0=B5=D0=BD=D0=B0=20=D0=B8=20?=
 =?UTF-8?q?=D1=83=D0=B4=D0=B0=D0=BB=D0=B5=D0=BD=D0=B8=D0=B5=20=D1=84=D0=B0?=
 =?UTF-8?q?=D0=B9=D0=BB=D0=BE=D0=B2,=20=D1=87=D0=B5=D1=80=D0=BD=D0=BE?=
 =?UTF-8?q?=D0=B2=D0=B8=D0=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- новый файл: имя → содержимое текстом (```-обёртка снимается) или документом
- новая папка (виртуальная, пока в ней нет файлов), замена с diff +N/−M, удаление
- валидация: имя, ≤ 100 КБ, UTF-8, без NUL; .py — ast.parse с выбором «исправить / всё равно»;
  .sourcecraft/, .tgit/, ruff.toml из бота не меняются
- DraftService: черновик в БД, 24 ч, ≤ 50 изменений; удаление нового файла убирает его из черновика
- дерево показывает черновик поверх репозитория: 🆕 / ✏️ / 🗑, размер — как будет после пуша
- экран черновика (A/M/D) с «↩️ убрать»

Refs #26

Co-Authored-By: Claude Opus 5.5 
---
 app/bot/routers/commit.py     | 457 ++++++++++++++++++++++++++++------
 app/main.py                   |   3 +-
 app/repo/drafts.py            | 107 ++++++++
 app/repo/validate.py          |  76 ++++++
 app/texts.py                  |  29 +++
 config/texts.yaml             |  29 +++
 tests/bot/test_commit.py      |   6 +-
 tests/bot/test_commit_edit.py | 162 ++++++++++++
 tests/fakes.py                |  27 +-
 tests/repo/test_drafts.py     |  72 ++++++
 tests/repo/test_validate.py   |  74 ++++++
 11 files changed, 951 insertions(+), 91 deletions(-)
 create mode 100644 app/repo/drafts.py
 create mode 100644 app/repo/validate.py
 create mode 100644 tests/bot/test_commit_edit.py
 create mode 100644 tests/repo/test_drafts.py
 create mode 100644 tests/repo/test_validate.py

diff --git a/app/bot/routers/commit.py b/app/bot/routers/commit.py
index 7864a17..965bd5e 100644
--- a/app/bot/routers/commit.py
+++ b/app/bot/routers/commit.py
@@ -1,20 +1,37 @@
-"""«📝 Коммит»: browsing the uploads repo tree with buttons (SPEC C-1…C-4). Changes and push — #26, #9."""
+"""«📝 Коммит»: browse the uploads repo tree and collect changes into a draft (SPEC C-1…C-16). Push — #9."""
 
+import base64
 import html
+import io
 import logging
+from dataclasses import dataclass
 from enum import StrEnum
 from typing import Any
 
-from aiogram import F, Router
+from aiogram import Bot, F, Router
 from aiogram.enums import ParseMode
 from aiogram.filters.callback_data import CallbackData
 from aiogram.fsm.context import FSMContext
+from aiogram.fsm.state import State, StatesGroup
 from aiogram.types import BufferedInputFile, CallbackQuery, InlineKeyboardMarkup, Message
 from aiogram.utils.keyboard import InlineKeyboardBuilder
 
 from app.bot.menu import Nav, NavAction
+from app.db.models import ChangeOp, User
+from app.repo.drafts import DraftFull, DraftService, DraftView
 from app.repo.git import Entry, GitError, UploadsRepo
-from app.texts import Texts
+from app.repo.validate import (
+    MAX_FILE_BYTES,
+    ValidationError,
+    check_content,
+    check_name,
+    diff_stat,
+    is_protected,
+    join,
+    python_syntax,
+    strip_fence,
+)
+from app.texts import CommitTexts, Texts
 
 log = logging.getLogger(__name__)
 
@@ -32,6 +49,10 @@ class Act(StrEnum):
     DELETE = "d"
     NEW_FILE = "f"
     NEW_DIR = "n"
+    DRAFT = "dr"
+    UNSTAGE = "x"
+    FORCE = "y"
+    FIX = "z"
 
 
 class CommitCb(CallbackData, prefix="c"):
@@ -40,6 +61,34 @@ class CommitCb(CallbackData, prefix="c"):
     i: int = 0
 
 
+class Flow(StatesGroup):
+    file_name = State()
+    dir_name = State()
+    content = State()
+    syntax = State()
+
+
+class Mark(StrEnum):
+    NONE = ""
+    NEW = "new"
+    MODIFIED = "mod"
+    DELETED = "del"
+
+
+@dataclass(frozen=True)
+class Row:
+    """A line of the directory screen: a repo entry with the draft laid over it."""
+
+    path: str
+    kind: str
+    size: int
+    mark: Mark
+
+    @property
+    def name(self) -> str:
+        return self.path.rsplit("/", 1)[-1]
+
+
 def human_size(n: int) -> str:
     size = float(n)
     for unit in ("Б", "КБ", "МБ"):
@@ -53,26 +102,61 @@ 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]:
+def overlay(path: str, entries: list[Entry], draft: DraftView | None, virtual_dirs: list[str]) -> list[Row]:
+    """Repo listing + what the draft adds, changes or deletes in this directory."""
+    changes = {c.path: c for c in draft.changes} if draft else {}
+    rows: dict[str, Row] = {}
+    for e in entries:
+        change = changes.get(e.path)
+        mark, size = Mark.NONE, e.size
+        if change is not None:
+            mark = Mark.DELETED if change.op is ChangeOp.DELETE else Mark.MODIFIED
+            if change.content is not None:
+                size = len(change.content)  # show the size the file will have after the push
+        rows[e.path] = Row(e.path, e.kind, size, mark)
+    prefix = f"{path}/" if path else ""
+    for change in changes.values():
+        if change.op is not ChangeOp.ADD or not change.path.startswith(prefix):
+            continue
+        rest = change.path[len(prefix) :]
+        if "/" in rest:  # a file deeper down: show its top folder here
+            sub = prefix + rest.split("/", 1)[0]
+            rows.setdefault(sub, Row(sub, "dir", 0, Mark.NEW))
+        else:
+            rows[change.path] = Row(change.path, "file", len(change.content or b""), Mark.NEW)
+    for vd in virtual_dirs:
+        if parent(vd) == path:
+            rows.setdefault(vd, Row(vd, "dir", 0, Mark.NEW))
+    return sorted(rows.values(), key=lambda r: (r.kind != "dir", r.name.lower()))
+
+
+def mark_prefix(t: CommitTexts, mark: Mark) -> str:
+    return {Mark.NONE: "", Mark.NEW: t.mark_new, Mark.MODIFIED: t.mark_modified, Mark.DELETED: t.mark_deleted}[mark]
+
+
+def render_dir(
+    texts: Texts, path: str, rows: list[Row], page: int, draft_count: int
+) -> tuple[str, InlineKeyboardMarkup]:
     t = texts.commit
-    pages = max(1, -(-len(entries) // PAGE_SIZE))
+    pages = max(1, -(-len(rows) // PAGE_SIZE))
     page = min(max(page, 0), pages - 1)
     lines = [t.title.format(path=path)]
-    if not entries:
+    if not rows:
         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))
+    shown = rows[start : start + PAGE_SIZE]
+    for index, r in enumerate(shown, start=start):
+        base = (
+            t.dir_button.format(name=r.name)
+            if r.kind == "dir"
+            else t.file_button.format(name=r.name, size=human_size(r.size))
         )
-        kb.button(text=label, callback_data=CommitCb(a=Act.OPEN, i=index))
-    sizes = [1] * min(PAGE_SIZE, max(0, len(entries) - start))
+        kb.button(text=mark_prefix(t, r.mark) + base, callback_data=CommitCb(a=Act.OPEN, i=index))
+    sizes = [1] * len(shown)
 
     paging: list[tuple[str, CommitCb]] = []
     if page > 0:
@@ -87,6 +171,9 @@ def render_dir(texts: Texts, path: str, entries: list[Entry], page: int) -> tupl
     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 draft_count:
+        kb.button(text=t.draft_button.format(count=draft_count), callback_data=CommitCb(a=Act.DRAFT))
+        sizes.append(1)
     if path:
         kb.button(text=t.up, callback_data=CommitCb(a=Act.UP))
         sizes.append(1)
@@ -108,80 +195,60 @@ def file_keyboard(texts: Texts) -> InlineKeyboardMarkup:
     return kb.as_markup()
 
 
-def build_router(texts: Texts, repo: UploadsRepo) -> Router:
+def to_dir_keyboard(texts: Texts) -> InlineKeyboardMarkup:
+    kb = InlineKeyboardBuilder()
+    kb.button(text=texts.commit.to_dir, callback_data=CommitCb(a=Act.TO_DIR))
+    return kb.as_markup()
+
+
+def build_router(texts: Texts, repo: UploadsRepo, drafts: DraftService) -> 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)
+    async def dir_screen(state: FSMContext, user_id: int, path: str, page: int) -> tuple[str, InlineKeyboardMarkup]:
+        data = await state.get_data()
+        virtual: list[str] = data.get("commit_virtual", [])
+        draft = await drafts.get(user_id)
+        try:
+            entries = await repo.list_dir(path)
+        except GitError:
+            # a folder that exists only in the draft (or a virtual one) has nothing in the repo yet
+            if path not in virtual and not (draft and any(c.path.startswith(f"{path}/") for c in draft.changes)):
+                raise
+            entries = []
+        rows = overlay(path, entries, draft, virtual)
         await state.update_data(
             commit_path=path,
             commit_page=page,
-            commit_entries=[[e.path, e.kind, e.size] for e in entries],
+            commit_rows=[[r.path, r.kind, r.size, r.mark.value] for r in rows],
             commit_file=None,
         )
-        text, kb = render_dir(texts, path, entries, page)
-        if edit:
-            await message.edit_text(text, reply_markup=kb)
+        return render_dir(texts, path, rows, page, len(draft.changes) if draft else 0)
+
+    async def draft_screen(state: FSMContext, user_id: int) -> tuple[str, InlineKeyboardMarkup]:
+        draft = await drafts.get(user_id)
+        changes = draft.changes if draft else []
+        await state.update_data(commit_draft=[c.path for c in changes])
+        kb = InlineKeyboardBuilder()
+        if not changes:
+            text = t.draft_empty
         else:
-            await message.answer(text, reply_markup=kb)
+            ops = {ChangeOp.ADD: t.op_add, ChangeOp.MODIFY: t.op_modify, ChangeOp.DELETE: t.op_delete}
+            lines = [t.draft_title.format(count=len(changes)), ""]
+            lines += [f"{ops[c.op]}  /{c.path}" for c in changes]
+            text = "\n".join(lines)
+            for i, c in enumerate(changes):
+                kb.button(
+                    text=t.unstage.format(name=c.path.rsplit("/", 1)[-1]), callback_data=CommitCb(a=Act.UNSTAGE, i=i)
+                )
+        kb.button(text=t.to_dir, callback_data=CommitCb(a=Act.TO_DIR))
+        kb.adjust(1)
+        return text, kb.as_markup()
 
-    @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:
+    async def file_card(user_id: int, path: str, size: int, mark: Mark) -> str:
         card = t.file_card.format(path=path, size=human_size(size))
+        if mark is Mark.NEW:
+            return f"{card}\n{t.in_draft_new}"
         info = await repo.last_commit(path)
         tail = (
             t.last_commit.format(
@@ -190,11 +257,21 @@ def build_router(texts: Texts, repo: UploadsRepo) -> Router:
             if info
             else t.no_commits
         )
-        return f"{card}\n{tail}"
+        note = {Mark.MODIFIED: f"\n{t.in_draft_modified}", Mark.DELETED: f"\n{t.in_draft_deleted}"}.get(mark, "")
+        return f"{card}\n{tail}{note}"
 
-    async def send_file(msg: Message, path: str) -> None:
-        content = await repo.read(path)
-        name = path.rsplit("/", 1)[-1]
+    async def current_content(user_id: int, path: str) -> bytes | None:
+        """What the member sees as the file now: the draft version if there is one."""
+        draft = await drafts.get(user_id)
+        change = draft.change_for(path) if draft else None
+        if change is not None:
+            return change.content  # None for a deleted file
+        return await repo.read(path)
+
+    async def send_file(msg: Message, user_id: int, path: str) -> None:
+        content = await current_content(user_id, path)
+        if content is None:
+            return
         try:
             text = content.decode("utf-8")
         except UnicodeDecodeError:
@@ -202,6 +279,224 @@ def build_router(texts: Texts, repo: UploadsRepo) -> Router:
         if text is not None and "\0" not in text and len(text) <= INLINE_VIEW_LIMIT:
             await msg.answer(f"/{html.escape(path)}\n
{html.escape(text)}
", parse_mode=ParseMode.HTML)
         else:
-            await msg.answer_document(BufferedInputFile(content, name), caption=t.sent_as_file)
+            await msg.answer_document(BufferedInputFile(content, path.rsplit("/", 1)[-1]), caption=t.sent_as_file)
+
+    async def stage(message: Message, state: FSMContext, member: User, path: str, op: ChangeOp, content: bytes) -> None:
+        old = await current_content(member.tg_id, path) if op is ChangeOp.MODIFY else None
+        try:
+            await drafts.put(member.tg_id, await repo.head(), path, op, content)
+        except DraftFull:
+            await message.answer(t.draft_full)
+            return
+        if op is ChangeOp.ADD:
+            note = t.added.format(path=path)
+        else:
+            added, removed = diff_stat((old or b"").decode("utf-8", errors="replace"), content.decode("utf-8"))
+            note = t.modified.format(path=path, added=added, removed=removed)
+        data = await state.get_data()
+        # a virtual folder becomes real as soon as a file lands in it
+        virtual = [v for v in data.get("commit_virtual", []) if not path.startswith(f"{v}/")]
+        await state.set_state(None)
+        await state.update_data(commit_virtual=virtual, commit_pending=None)
+        text, kb = await dir_screen(state, member.tg_id, data.get("commit_path", ""), 0)
+        await message.answer(f"{note}\n\n{text}", reply_markup=kb)
+
+    # ---- entry point -------------------------------------------------------------------------------------------
+
+    @router.message(F.text == texts.menu.commit)
+    async def open_commit(message: Message, state: FSMContext, member: User) -> None:
+        await state.clear()
+        try:
+            await repo.refresh()
+            text, kb = await dir_screen(state, member.tg_id, "", 0)
+        except GitError:
+            log.exception("uploads repo unavailable")
+            await message.answer(t.unavailable)
+            return
+        await message.answer(text, reply_markup=kb)
+
+    # ---- buttons -----------------------------------------------------------------------------------------------
+
+    @router.callback_query(CommitCb.filter())
+    async def on_action(query: CallbackQuery, callback_data: CommitCb, state: FSMContext, member: User) -> 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", "")
+        rows: list[list[Any]] = data.get("commit_rows", [])
+        uid = member.tg_id
+        try:
+            match callback_data.a:
+                case Act.OPEN:
+                    if not 0 <= callback_data.i < len(rows):
+                        await query.answer()  # stale button from an older screen
+                        return
+                    target, kind, size, mark = rows[callback_data.i]
+                    if kind == "dir":
+                        await repo.refresh()
+                        text, kb = await dir_screen(state, uid, target, 0)
+                        await msg.edit_text(text, reply_markup=kb)
+                    else:
+                        await state.update_data(commit_file=target)
+                        await msg.edit_text(
+                            await file_card(uid, target, size, Mark(mark)), reply_markup=file_keyboard(texts)
+                        )
+                case Act.UP:
+                    text, kb = await dir_screen(state, uid, parent(path), 0)
+                    await msg.edit_text(text, reply_markup=kb)
+                case Act.PAGE:
+                    real = [Row(p, k, s, Mark(m)) for p, k, s, m in rows]
+                    draft = await drafts.get(uid)
+                    await state.update_data(commit_page=callback_data.i)
+                    text, kb = render_dir(texts, path, real, callback_data.i, len(draft.changes) if draft else 0)
+                    await msg.edit_text(text, reply_markup=kb)
+                case Act.TO_DIR:
+                    await state.set_state(None)
+                    text, kb = await dir_screen(state, uid, path, data.get("commit_page", 0))
+                    await msg.edit_text(text, reply_markup=kb)
+                case Act.VIEW:
+                    if data.get("commit_file"):
+                        await send_file(msg, uid, data["commit_file"])
+                case Act.NEW_FILE:
+                    await state.set_state(Flow.file_name)
+                    await msg.edit_text(t.ask_file_name.format(dir=path), reply_markup=to_dir_keyboard(texts))
+                case Act.NEW_DIR:
+                    await state.set_state(Flow.dir_name)
+                    await msg.edit_text(t.ask_dir_name.format(dir=path), reply_markup=to_dir_keyboard(texts))
+                case Act.REPLACE:
+                    target = data.get("commit_file")
+                    if not target:
+                        await query.answer()
+                        return
+                    if is_protected(target):
+                        await query.answer(t.protected, show_alert=True)
+                        return
+                    await state.set_state(Flow.content)
+                    await state.update_data(commit_target=target, commit_op=ChangeOp.MODIFY.value)
+                    await msg.edit_text(t.ask_content.format(path=target), reply_markup=to_dir_keyboard(texts))
+                case Act.DELETE:
+                    target = data.get("commit_file")
+                    if not target:
+                        await query.answer()
+                        return
+                    if is_protected(target):
+                        await query.answer(t.protected, show_alert=True)
+                        return
+                    await drafts.put(uid, await repo.head(), target, ChangeOp.DELETE, None)
+                    text, kb = await dir_screen(state, uid, path, data.get("commit_page", 0))
+                    await msg.edit_text(f"{t.deleted.format(path=target)}\n\n{text}", reply_markup=kb)
+                case Act.DRAFT:
+                    text, kb = await draft_screen(state, uid)
+                    await msg.edit_text(text, reply_markup=kb)
+                case Act.UNSTAGE:
+                    paths: list[str] = data.get("commit_draft", [])
+                    if 0 <= callback_data.i < len(paths):
+                        await drafts.drop(uid, paths[callback_data.i])
+                    text, kb = await draft_screen(state, uid)
+                    await msg.edit_text(text, reply_markup=kb)
+                case Act.FORCE:
+                    pending = data.get("commit_pending")
+                    if pending is None or await state.get_state() != Flow.syntax.state:
+                        await query.answer()
+                        return
+                    await query.answer()
+                    await stage(
+                        msg,
+                        state,
+                        member,
+                        data["commit_target"],
+                        ChangeOp(data["commit_op"]),
+                        base64.b64decode(pending),
+                    )
+                    return
+                case Act.FIX:
+                    await state.set_state(Flow.content)
+                    await state.update_data(commit_pending=None)
+                    await msg.edit_text(
+                        t.ask_content.format(path=data.get("commit_target", "")), reply_markup=to_dir_keyboard(texts)
+                    )
+        except GitError:
+            log.exception("uploads repo unavailable")
+            await query.answer(t.unavailable, show_alert=True)
+            return
+        except DraftFull:
+            await query.answer(t.draft_full, show_alert=True)
+            return
+        await query.answer()
+
+    # ---- text input --------------------------------------------------------------------------------------------
+
+    @router.message(Flow.file_name, F.text)
+    async def got_file_name(message: Message, state: FSMContext, member: User) -> None:
+        data = await state.get_data()
+        directory = data.get("commit_path", "")
+        try:
+            name = check_name(message.text or "")
+        except ValidationError:
+            await message.answer(t.bad_name)
+            return
+        path = join(directory, name)
+        if is_protected(path):
+            await message.answer(t.protected)
+            return
+        taken = {row[0] for row in data.get("commit_rows", [])}
+        if path in taken:
+            await message.answer(t.exists)
+            return
+        await state.set_state(Flow.content)
+        await state.update_data(commit_target=path, commit_op=ChangeOp.ADD.value)
+        await message.answer(t.ask_content.format(path=path), reply_markup=to_dir_keyboard(texts))
+
+    @router.message(Flow.dir_name, F.text)
+    async def got_dir_name(message: Message, state: FSMContext, member: User) -> None:
+        data = await state.get_data()
+        directory = data.get("commit_path", "")
+        try:
+            name = check_name(message.text or "")
+        except ValidationError:
+            await message.answer(t.bad_name)
+            return
+        path = join(directory, name)
+        if is_protected(path + "/x"):
+            await message.answer(t.protected)
+            return
+        if path in {row[0] for row in data.get("commit_rows", [])}:
+            await message.answer(t.exists)
+            return
+        await state.set_state(None)
+        await state.update_data(commit_virtual=[*data.get("commit_virtual", []), path])
+        text, kb = await dir_screen(state, member.tg_id, path, 0)
+        await message.answer(text, reply_markup=kb)
+
+    @router.message(Flow.content, F.text | F.document)
+    async def got_content(message: Message, state: FSMContext, member: User, bot: Bot) -> None:
+        data = await state.get_data()
+        target: str = data["commit_target"]
+        if message.document is not None:
+            if (message.document.file_size or 0) > MAX_FILE_BYTES:
+                await message.answer(t.too_big)
+                return
+            buf = io.BytesIO()
+            await bot.download(message.document, destination=buf)
+            raw = buf.getvalue()
+        else:
+            raw = strip_fence(message.text or "").encode("utf-8")
+        try:
+            text = check_content(raw)
+        except ValidationError as e:
+            await message.answer({"too_big": t.too_big, "binary": t.binary, "encoding": t.encoding}[str(e)])
+            return
+        issue = python_syntax(target, text)
+        if issue is not None:
+            await state.set_state(Flow.syntax)
+            await state.update_data(commit_pending=base64.b64encode(raw).decode())
+            kb = InlineKeyboardBuilder()
+            kb.button(text=t.fix, callback_data=CommitCb(a=Act.FIX))
+            kb.button(text=t.force, callback_data=CommitCb(a=Act.FORCE))
+            await message.answer(t.syntax.format(line=issue.line, message=issue.message), reply_markup=kb.as_markup())
+            return
+        await stage(message, state, member, target, ChangeOp(data["commit_op"]), raw)
 
     return router
diff --git a/app/main.py b/app/main.py
index 1be8a8e..d0a4d49 100644
--- a/app/main.py
+++ b/app/main.py
@@ -17,6 +17,7 @@ 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.drafts import DraftService
 from app.repo.git import UploadsRepo
 from app.texts import Texts, load_texts
 
@@ -30,7 +31,7 @@ def build_dispatcher(texts: Texts, sessions: SessionMaker, access: AccessService
     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(commit.build_router(texts, repo, DraftService(sessions)))
     dp.include_router(common.build_router(texts, access))
     return dp
 
diff --git a/app/repo/drafts.py b/app/repo/drafts.py
new file mode 100644
index 0000000..81ca43e
--- /dev/null
+++ b/app/repo/drafts.py
@@ -0,0 +1,107 @@
+"""A member's draft: pending add/modify/delete changes until Push (SPEC C-14, C-15). One draft per member."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.db.models import ChangeOp, Draft, DraftChange, utcnow
+from app.db.session import SessionMaker
+
+MAX_CHANGES = 50
+
+
+class DraftFull(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Change:
+    path: str
+    op: ChangeOp
+    content: bytes | None
+
+
+@dataclass(frozen=True)
+class DraftView:
+    base_sha: str
+    message: str | None
+    changes: list[Change]
+
+    def change_for(self, path: str) -> Change | None:
+        return next((c for c in self.changes if c.path == path), None)
+
+
+class DraftService:
+    def __init__(
+        self, sessions: SessionMaker, ttl: timedelta = timedelta(hours=24), clock: Callable[[], datetime] = utcnow
+    ):
+        self._sessions = sessions
+        self._ttl = ttl
+        self._clock = clock
+
+    async def get(self, user_id: int) -> DraftView | None:
+        async with self._sessions() as s:
+            draft = await self._load(s, user_id)
+            if draft is None:
+                return None
+            return DraftView(
+                base_sha=draft.base_sha,
+                message=draft.message,
+                changes=[Change(c.path, c.op, c.content) for c in draft.changes],
+            )
+
+    async def put(self, user_id: int, base_sha: str, path: str, op: ChangeOp, content: bytes | None) -> None:
+        """Record a change. Deleting a file that only exists in the draft just drops it from the draft."""
+        async with self._sessions.begin() as s:
+            draft = await self._load(s, user_id)
+            if draft is None:
+                draft = Draft(
+                    user_id=user_id, base_sha=base_sha, created_at=self._clock(), expires_at=self._clock() + self._ttl
+                )
+                s.add(draft)
+            existing = next((c for c in draft.changes if c.path == path), None)
+            if existing is not None:
+                if op is ChangeOp.DELETE and existing.op is ChangeOp.ADD:
+                    draft.changes.remove(existing)
+                    return
+                # editing a file added in this draft keeps it an "add"
+                existing.op = ChangeOp.ADD if existing.op is ChangeOp.ADD and op is ChangeOp.MODIFY else op
+                existing.content = content
+            else:
+                if len(draft.changes) >= MAX_CHANGES:
+                    raise DraftFull
+                draft.changes.append(DraftChange(path=path, op=op, content=content))
+            draft.expires_at = self._clock() + self._ttl
+
+    async def drop(self, user_id: int, path: str) -> None:
+        async with self._sessions.begin() as s:
+            draft = await self._load(s, user_id)
+            if draft is None:
+                return
+            draft.changes = [c for c in draft.changes if c.path != path]
+
+    async def set_message(self, user_id: int, message: str) -> None:
+        async with self._sessions.begin() as s:
+            draft = await self._load(s, user_id)
+            if draft is not None:
+                draft.message = message
+
+    async def clear(self, user_id: int) -> None:
+        async with self._sessions.begin() as s:
+            await s.execute(delete(Draft).where(Draft.user_id == user_id))
+
+    async def _load(self, s: AsyncSession, user_id: int) -> Draft | None:
+        draft = await s.scalar(select(Draft).where(Draft.user_id == user_id).options(selectinload(Draft.changes)))
+        if draft is not None and _aware(draft.expires_at) <= self._clock():
+            await s.delete(draft)
+            await s.flush()
+            return None
+        return draft
+
+
+def _aware(value: datetime) -> datetime:
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
diff --git a/app/repo/validate.py b/app/repo/validate.py
new file mode 100644
index 0000000..e0a7447
--- /dev/null
+++ b/app/repo/validate.py
@@ -0,0 +1,76 @@
+"""Checks for names and file contents before anything goes into a draft (SPEC C-10, C-12, C-16). No code runs here."""
+
+import ast
+import difflib
+import re
+from dataclasses import dataclass
+
+MAX_FILE_BYTES = 100 * 1024
+NAME = re.compile(r"^[A-Za-z0-9._-]{1,100}$")
+# Bot users can't touch the CI of the uploads repo or its helper scripts (SPEC C-16, ADR-014)
+PROTECTED_PREFIXES = (".sourcecraft/", ".tgit/", ".git/")
+PROTECTED_FILES = {"ruff.toml"}
+_FENCE = re.compile(r"^\s*```[\w+-]*[ \t]*\n(.*?)\n?```\s*$", re.DOTALL)
+
+
+class ValidationError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class SyntaxIssue:
+    line: int
+    message: str
+
+
+def check_name(name: str) -> str:
+    name = name.strip()
+    if not NAME.match(name) or name in {".", ".."}:
+        raise ValidationError("name")
+    return name
+
+
+def is_protected(path: str) -> bool:
+    return path in PROTECTED_FILES or any(path.startswith(p) or path + "/" == p for p in PROTECTED_PREFIXES)
+
+
+def join(directory: str, name: str) -> str:
+    return f"{directory}/{name}" if directory else name
+
+
+def strip_fence(text: str) -> str:
+    """Code pasted as a Telegram message often comes wrapped in ``` — keep only what's inside."""
+    match = _FENCE.match(text)
+    return match.group(1) if match else text
+
+
+def check_content(data: bytes) -> str:
+    """Size, encoding, NUL bytes. Returns the decoded text."""
+    if len(data) > MAX_FILE_BYTES:
+        raise ValidationError("too_big")
+    if b"\0" in data:
+        raise ValidationError("binary")
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        raise ValidationError("encoding") from None
+
+
+def python_syntax(path: str, text: str) -> SyntaxIssue | None:
+    if not path.endswith(".py"):
+        return None
+    try:
+        ast.parse(text, filename=path)
+    except SyntaxError as e:
+        return SyntaxIssue(line=e.lineno or 0, message=e.msg)
+    return None
+
+
+def diff_stat(old: str, new: str) -> tuple[int, int]:
+    added = removed = 0
+    for line in difflib.ndiff(old.splitlines(), new.splitlines()):
+        if line.startswith("+ "):
+            added += 1
+        elif line.startswith("- "):
+            removed += 1
+    return added, removed
diff --git a/app/texts.py b/app/texts.py
index e1c0724..53d7f79 100644
--- a/app/texts.py
+++ b/app/texts.py
@@ -75,6 +75,35 @@ class CommitTexts(_Strict):
     soon: str
     unavailable: str
     sent_as_file: str
+    ask_file_name: str
+    ask_dir_name: str
+    bad_name: str
+    exists: str
+    protected: str
+    ask_content: str
+    too_big: str
+    binary: str
+    encoding: str
+    syntax: str
+    fix: str
+    force: str
+    added: str
+    modified: str
+    deleted: str
+    draft_button: str
+    draft_title: str
+    draft_empty: str
+    unstage: str
+    draft_full: str
+    in_draft_new: str
+    in_draft_modified: str
+    in_draft_deleted: str
+    mark_new: str
+    mark_modified: str
+    mark_deleted: str
+    op_add: str
+    op_modify: str
+    op_delete: str
 
 
 class Texts(_Strict):
diff --git a/config/texts.yaml b/config/texts.yaml
index 9ff6a6b..8dcd4b1 100644
--- a/config/texts.yaml
+++ b/config/texts.yaml
@@ -78,3 +78,32 @@ commit:
   soon: "Будет в следующей версии."
   unavailable: "Репозиторий загрузок недоступен, попробуйте через минуту."
   sent_as_file: "Файл большой или бинарный — отправил документом."
+  ask_file_name: "Имя нового файла в /{dir} (латиница, цифры, «.», «_», «-»):"
+  ask_dir_name: "Имя новой папки в /{dir}:"
+  bad_name: "Недопустимое имя: латиница, цифры, «.», «_», «-», до 100 символов. Пришлите другое."
+  exists: "Такое имя уже есть в этой папке. Пришлите другое."
+  protected: "Это служебный путь репозитория — из бота его менять нельзя."
+  ask_content: "Пришлите содержимое /{path} — текстом сообщения или файлом (до 100 КБ)."
+  too_big: "Больше 100 КБ — не принимаю."
+  binary: "Похоже на бинарный файл — принимаю только текст."
+  encoding: "Файл не в кодировке UTF-8."
+  syntax: "⚠️ Синтаксическая ошибка, строка {line}: {message}"
+  fix: "✏️ Исправить"
+  force: "Всё равно добавить"
+  added: "🆕 /{path} — добавлен в черновик."
+  modified: "✏️ /{path} — в черновике: +{added} −{removed}."
+  deleted: "🗑 /{path} — в черновике на удаление."
+  draft_button: "🧾 Черновик · {count}"
+  draft_title: "🧾 Черновик · изменений: {count}"
+  draft_empty: "Черновик пуст."
+  unstage: "↩️ убрать {name}"
+  draft_full: "В черновике уже 50 изменений — запушьте или уберите лишнее."
+  in_draft_new: "В черновике: новый файл."
+  in_draft_modified: "В черновике: изменён."
+  in_draft_deleted: "В черновике: удалён."
+  mark_new: "🆕 "
+  mark_modified: "✏️ "
+  mark_deleted: "🗑 "
+  op_add: "A"
+  op_modify: "M"
+  op_delete: "D"
diff --git a/tests/bot/test_commit.py b/tests/bot/test_commit.py
index 43f8096..0e04cc4 100644
--- a/tests/bot/test_commit.py
+++ b/tests/bot/test_commit.py
@@ -87,13 +87,11 @@ async def test_pagination(tg: TgClient, texts: Texts) -> None:
     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:
+async def test_stale_button_is_ignored(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
+    [stale] = tg.session.sent(AnswerCallbackQuery)
     assert stale.text is None
     assert tg.session.sent(EditMessageText) == []
 
diff --git a/tests/bot/test_commit_edit.py b/tests/bot/test_commit_edit.py
new file mode 100644
index 0000000..47601f1
--- /dev/null
+++ b/tests/bot/test_commit_edit.py
@@ -0,0 +1,162 @@
+import pytest
+from aiogram.methods import AnswerCallbackQuery, EditMessageText, SendMessage
+from aiogram.types import InlineKeyboardMarkup
+
+from app.access.service import AccessService
+from app.bot.routers.commit import Act, CommitCb
+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 cb(action: Act, i: int = 0) -> str:
+    return CommitCb(a=action, i=i).pack()
+
+
+def labels(markup: object) -> list[str]:
+    assert isinstance(markup, InlineKeyboardMarkup)
+    return [b.text for row in markup.inline_keyboard for b in row]
+
+
+def last_text(tg: TgClient) -> SendMessage:
+    return tg.session.sent(SendMessage)[-1]
+
+
+async def to_hello(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
+
+
+async def test_new_file_from_fenced_text(tg: TgClient, texts: Texts) -> None:
+    await to_hello(tg, texts)
+    await tg.press(ADMIN, cb(Act.NEW_FILE))
+    await tg.send(ADMIN, "utils.py")
+    await tg.send(ADMIN, "```python\ndef add(a, b):\n    return a + b\n```")
+
+    reply = last_text(tg)
+    assert reply.text.startswith(texts.commit.added.format(path="services/hello/utils.py"))
+    got = labels(reply.reply_markup)
+    assert "🆕 📄 utils.py · 31 Б" in got  # fence stripped, no trailing newline
+    assert texts.commit.draft_button.format(count=1) in got
+
+    await tg.press(ADMIN, cb(Act.OPEN, 1))  # utils.py (main.py is 0)
+    await tg.press(ADMIN, cb(Act.VIEW))
+    view = last_text(tg)
+    assert "def add(a, b):" in view.text and "```" not in view.text
+
+
+async def test_replace_with_document_shows_diff(tg: TgClient, texts: Texts) -> None:
+    await to_hello(tg, texts)
+    await tg.press(ADMIN, cb(Act.OPEN, 0))  # main.py
+    await tg.press(ADMIN, cb(Act.REPLACE))
+    await tg.send_document(ADMIN, "main.py", b"print('hello')\nprint('bye')\n")
+
+    reply = last_text(tg)
+    assert reply.text.startswith(texts.commit.modified.format(path="services/hello/main.py", added=1, removed=0))
+    assert "✏️ 📄 main.py · 28 Б" in labels(reply.reply_markup)
+
+
+async def test_delete_marks_and_draft_lists(tg: TgClient, texts: Texts) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+    await tg.press(ADMIN, cb(Act.OPEN, 3))  # README.md
+    await tg.press(ADMIN, cb(Act.DELETE))
+    deleted = tg.session.sent(EditMessageText)[-1]
+    assert deleted.text.startswith(texts.commit.deleted.format(path="README.md"))
+    assert "🗑 📄 README.md · 10 Б" in labels(deleted.reply_markup)
+
+    await tg.press(ADMIN, cb(Act.DRAFT))
+    draft = tg.session.sent(EditMessageText)[-1]
+    assert "D  /README.md" in draft.text
+
+    await tg.press(ADMIN, cb(Act.UNSTAGE, 0))
+    assert tg.session.sent(EditMessageText)[-1].text == texts.commit.draft_empty
+
+
+async def test_syntax_error_force_or_fix(tg: TgClient, texts: Texts) -> None:
+    await to_hello(tg, texts)
+    await tg.press(ADMIN, cb(Act.NEW_FILE))
+    await tg.send(ADMIN, "bad.py")
+    await tg.send(ADMIN, "def f(:\n    pass")
+
+    warn = last_text(tg)
+    assert warn.text.startswith("⚠️") and "1" in warn.text
+    assert labels(warn.reply_markup) == [texts.commit.fix, texts.commit.force]
+
+    await tg.press(ADMIN, cb(Act.FIX))
+    assert tg.session.sent(EditMessageText)[-1].text == texts.commit.ask_content.format(path="services/hello/bad.py")
+    await tg.send(ADMIN, "def f(:\n    pass")
+    await tg.press(ADMIN, cb(Act.FORCE))
+    assert last_text(tg).text.startswith(texts.commit.added.format(path="services/hello/bad.py"))
+
+
+async def test_virtual_folder_becomes_real_with_a_file(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.NEW_DIR))
+    await tg.send(ADMIN, "api")
+    inside = last_text(tg)
+    assert inside.text == f"{texts.commit.title.format(path='services/api')}\n{texts.commit.empty}"
+
+    await tg.press(ADMIN, cb(Act.NEW_FILE))
+    await tg.send(ADMIN, "main.py")
+    await tg.send(ADMIN, "print('api')")
+    await tg.press(ADMIN, cb(Act.UP))
+
+    services = tg.session.sent(EditMessageText)[-1]
+    assert "🆕 📁 api" in labels(services.reply_markup)
+
+
+async def test_names_rejected(tg: TgClient, texts: Texts) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+    await tg.press(ADMIN, cb(Act.NEW_FILE))
+    for bad in ["../etc", "README.md", "ruff.toml"]:
+        await tg.send(ADMIN, bad)
+
+    assert [m.text for m in tg.session.sent(SendMessage)][-3:] == [
+        texts.commit.bad_name,
+        texts.commit.exists,
+        texts.commit.protected,
+    ]
+
+
+async def test_binary_document_rejected(tg: TgClient, texts: Texts) -> None:
+    await to_hello(tg, texts)
+    await tg.press(ADMIN, cb(Act.NEW_FILE))
+    await tg.send(ADMIN, "img.png")
+    await tg.send_document(ADMIN, "img.png", b"\x89PNG\x00\x00")
+
+    assert last_text(tg).text == texts.commit.binary
+
+
+async def test_draft_survives_a_restart(
+    texts: Texts, sessions: SessionMaker, access: AccessService, repo: UploadsRepo
+) -> None:
+    first = TgClient(build_dispatcher(texts, sessions, access, repo))
+    await first.send(ADMIN, texts.menu.commit)
+    await first.press(ADMIN, cb(Act.OPEN, 3))
+    await first.press(ADMIN, cb(Act.DELETE))
+
+    second = TgClient(build_dispatcher(texts, sessions, access, repo))  # same DB, new bot process
+    await second.send(ADMIN, texts.menu.commit)
+    assert texts.commit.draft_button.format(count=1) in labels(second.session.sent(SendMessage)[-1].reply_markup)
+
+
+async def test_protected_file_cannot_be_replaced(tg: TgClient, texts: Texts, repo: UploadsRepo) -> None:
+    await tg.send(ADMIN, texts.menu.commit)
+    # fake a card for a protected path via FSM: open README then rewrite the selection
+    await tg.press(ADMIN, cb(Act.OPEN, 3))
+    state = tg.dp.fsm.get_context(tg.bot, chat_id=ADMIN, user_id=ADMIN)
+    await state.update_data(commit_file=".sourcecraft/ci.yaml")
+    await tg.press(ADMIN, cb(Act.REPLACE))
+
+    answer = tg.session.sent(AnswerCallbackQuery)[-1]
+    assert answer.text == texts.commit.protected and answer.show_alert
diff --git a/tests/fakes.py b/tests/fakes.py
index f03867d..a563e04 100644
--- a/tests/fakes.py
+++ b/tests/fakes.py
@@ -7,9 +7,9 @@ from typing import Any
 
 from aiogram import Bot, Dispatcher
 from aiogram.client.session.base import BaseSession
-from aiogram.methods import EditMessageText, GetMe, SendMessage, SendPhoto, TelegramMethod
+from aiogram.methods import EditMessageText, GetFile, GetMe, SendMessage, SendPhoto, TelegramMethod
 from aiogram.methods.base import TelegramType
-from aiogram.types import Chat, Message, Update, User
+from aiogram.types import Chat, File, Message, Update, User
 
 BOT_TOKEN = "42:TEST-TOKEN"
 
@@ -19,6 +19,7 @@ class FakeSession(BaseSession):
         super().__init__()
         self.requests: list[TelegramMethod[Any]] = []
         self._ids = count(1000)
+        self.files: dict[str, bytes] = {}  # file_id -> content, for documents users "upload"
 
     async def make_request(
         self,
@@ -27,6 +28,10 @@ class FakeSession(BaseSession):
         timeout: int | None = None,  # noqa: ASYNC109 - signature fixed by aiogram BaseSession
     ) -> TelegramType:
         self.requests.append(method)
+        if isinstance(method, GetFile):
+            return File(  # type: ignore[return-value]
+                file_id=method.file_id, file_unique_id=method.file_id, file_path=f"documents/{method.file_id}"
+            )
         if isinstance(method, GetMe):
             return User(id=42, is_bot=True, first_name="tgit", username="tgit_test_bot")  # type: ignore[return-value]
         if isinstance(method, SendPhoto):
@@ -54,9 +59,9 @@ class FakeSession(BaseSession):
         timeout: int = 30,  # noqa: ASYNC109 - signature fixed by aiogram BaseSession
         chunk_size: int = 65536,
         raise_for_status: bool = True,
-    ) -> AsyncGenerator[bytes, None]:  # pragma: no cover - not used
-        raise NotImplementedError
-        yield b""
+    ) -> AsyncGenerator[bytes, None]:
+        file_id = url.rsplit("/", 1)[-1]
+        yield self.files[file_id]
 
     async def close(self) -> None:
         pass
@@ -92,6 +97,18 @@ class TgClient:
             message["entities"] = [{"type": "bot_command", "offset": 0, "length": len(cmd)}]
         await self._feed({"message": message})
 
+    async def send_document(self, tg_id: int, name: str, content: bytes) -> None:
+        file_id = f"doc{next(self._message_ids)}"
+        self.session.files[file_id] = content
+        message = {
+            "message_id": next(self._message_ids),
+            "date": int(datetime.now(UTC).timestamp()),
+            "chat": {"id": tg_id, "type": "private"},
+            "from": self.user(tg_id),
+            "document": {"file_id": file_id, "file_unique_id": file_id, "file_name": name, "file_size": len(content)},
+        }
+        await self._feed({"message": message})
+
     async def press(self, tg_id: int, data: str, message_text: str = "section") -> None:
         callback = {
             "id": str(next(self._update_ids)),
diff --git a/tests/repo/test_drafts.py b/tests/repo/test_drafts.py
new file mode 100644
index 0000000..5802d4f
--- /dev/null
+++ b/tests/repo/test_drafts.py
@@ -0,0 +1,72 @@
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from app.db.models import ChangeOp, User
+from app.db.session import SessionMaker
+from app.repo.drafts import MAX_CHANGES, DraftFull, DraftService
+
+UID = 7
+SHA = "a" * 40
+
+
+class Clock:
+    now = datetime(2026, 10, 15, tzinfo=UTC)
+
+    def __call__(self) -> datetime:
+        return self.now
+
+
+@pytest.fixture
+async def svc(sessions: SessionMaker) -> DraftService:
+    async with sessions.begin() as s:
+        s.add(User(tg_id=UID, full_name="u"))
+    return DraftService(sessions, clock=Clock())
+
+
+async def test_put_get_and_order(svc: DraftService) -> None:
+    await svc.put(UID, SHA, "b.py", ChangeOp.ADD, b"b")
+    await svc.put(UID, "other-sha", "a.py", ChangeOp.MODIFY, b"a")
+
+    draft = await svc.get(UID)
+    assert draft is not None and draft.base_sha == SHA  # base fixed when the draft started
+    assert [(c.path, c.op) for c in draft.changes] == [("b.py", ChangeOp.ADD), ("a.py", ChangeOp.MODIFY)]
+
+
+async def test_editing_a_new_file_keeps_it_added_and_deleting_it_drops_it(svc: DraftService) -> None:
+    await svc.put(UID, SHA, "n.py", ChangeOp.ADD, b"1")
+    await svc.put(UID, SHA, "n.py", ChangeOp.MODIFY, b"2")
+    draft = await svc.get(UID)
+    assert draft is not None and draft.changes[0].op is ChangeOp.ADD and draft.changes[0].content == b"2"
+
+    await svc.put(UID, SHA, "n.py", ChangeOp.DELETE, None)
+    draft = await svc.get(UID)
+    assert draft is not None and draft.changes == []
+
+
+async def test_drop_message_clear(svc: DraftService) -> None:
+    await svc.put(UID, SHA, "a.py", ChangeOp.ADD, b"1")
+    await svc.put(UID, SHA, "b.py", ChangeOp.DELETE, None)
+    await svc.drop(UID, "a.py")
+    await svc.set_message(UID, "feat: x")
+
+    draft = await svc.get(UID)
+    assert draft is not None and [c.path for c in draft.changes] == ["b.py"] and draft.message == "feat: x"
+    await svc.clear(UID)
+    assert await svc.get(UID) is None
+
+
+async def test_expired_draft_is_gone(svc: DraftService) -> None:
+    await svc.put(UID, SHA, "a.py", ChangeOp.ADD, b"1")
+    Clock.now += timedelta(hours=25)
+    try:
+        assert await svc.get(UID) is None
+    finally:
+        Clock.now -= timedelta(hours=25)
+
+
+async def test_draft_size_limit(svc: DraftService) -> None:
+    for i in range(MAX_CHANGES):
+        await svc.put(UID, SHA, f"f{i}.py", ChangeOp.ADD, b"")
+    with pytest.raises(DraftFull):
+        await svc.put(UID, SHA, "one-more.py", ChangeOp.ADD, b"")
diff --git a/tests/repo/test_validate.py b/tests/repo/test_validate.py
new file mode 100644
index 0000000..5c48fdb
--- /dev/null
+++ b/tests/repo/test_validate.py
@@ -0,0 +1,74 @@
+import pytest
+
+from app.repo.validate import (
+    ValidationError,
+    check_content,
+    check_name,
+    diff_stat,
+    is_protected,
+    join,
+    python_syntax,
+    strip_fence,
+)
+
+
+@pytest.mark.parametrize("name", ["main.py", "a-b_c.1", ".gitignore", "X" * 100])
+def test_good_names(name: str) -> None:
+    assert check_name(f"  {name} ") == name
+
+
+@pytest.mark.parametrize("name", ["", ".", "..", "a/b", "привет.py", "a b", "X" * 101, "a;rm"])
+def test_bad_names(name: str) -> None:
+    with pytest.raises(ValidationError):
+        check_name(name)
+
+
+@pytest.mark.parametrize(
+    ("path", "protected"),
+    [
+        (".sourcecraft/ci.yaml", True),
+        (".tgit/x.py", True),
+        ("ruff.toml", True),
+        (".sourcecraft", True),
+        ("services/a/ruff.toml", False),
+        ("README.md", False),
+        ("services/a/main.py", False),
+    ],
+)
+def test_protected_paths(path: str, protected: bool) -> None:
+    assert is_protected(path) is protected
+
+
+def test_join() -> None:
+    assert join("", "a.py") == "a.py" and join("s/x", "a.py") == "s/x/a.py"
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [
+        ("```python\nprint(1)\n```", "print(1)"),
+        ("```\na\nb\n```", "a\nb"),
+        ("print(1)", "print(1)"),
+        ("x ``` y", "x ``` y"),
+    ],
+)
+def test_strip_fence(text: str, expected: str) -> None:
+    assert strip_fence(text) == expected
+
+
+def test_content_checks() -> None:
+    assert check_content("привет".encode()) == "привет"
+    for data, reason in [(b"a\0b", "binary"), (b"\xff\xfe", "encoding"), (b"x" * (100 * 1024 + 1), "too_big")]:
+        with pytest.raises(ValidationError, match=reason):
+            check_content(data)
+
+
+def test_python_syntax_only_for_py() -> None:
+    issue = python_syntax("a.py", "def f(:\n    pass\n")
+    assert issue is not None and issue.line == 1
+    assert python_syntax("a.py", "x = 1\n") is None
+    assert python_syntax("a.txt", "def f(:") is None
+
+
+def test_diff_stat() -> None:
+    assert diff_stat("a\nb\nc", "a\nB\nc\nd") == (2, 1)

From ae0cd5d42d533f0a3971ce19da69b61d7f7aea0f Mon Sep 17 00:00:00 2001
From: Lacky1234union 
Date: Thu, 15 Oct 2026 19:23:09 +0300
Subject: [PATCH 4/4] =?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=D1=81=D0=BE=D0=BE=D0=B1=D1=89=D0=B5=D0=BD?=
 =?UTF-8?q?=D0=B8=D0=B5,=20Push,=20=D0=BA=D0=BE=D0=BD=D1=84=D0=BB=D0=B8?=
 =?UTF-8?q?=D0=BA=D1=82=D1=8B,=20=D0=BF=D1=83=D0=B1=D0=BB=D0=B8=D0=BA?=
 =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8F=20=D0=B2=20=D1=80=D0=B5=D0=BF=D0=BE?=
 =?UTF-8?q?=D0=B7=D0=B8=D1=82=D0=BE=D1=80=D0=B8=D0=B9=20=D0=B7=D0=B0=D0=B3?=
 =?UTF-8?q?=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

- Publisher: пуши по одному (lock), fetch → проверка конфликта с base_sha → чистое дерево
  origin/main → черновик → коммит от tgit-bot с трейлером Telegram-User → push;
  отказ push → rebase и повтор (до 3 раз); защита от путей вне клона; лимит 20 пушей/час
- «💬 Сообщение коммита» (1–200 символов, первая строка ≤ 72) и «🚀 Push» с подтверждением;
  исходы: запушено (sha, ссылка, ⏳ CI) · конфликт → «Перезаписать» · нечего коммитить · лимит · сбой
- запись в pushes (chat_id, message_id — для обновления статуса CI/CD в #11), черновик очищается
- ruff: RUF001–003 выключены — кириллица в текстах это норма

Refs #9

Co-Authored-By: Claude Opus 5.5 
---
 app/bot/routers/commit.py     |  84 ++++++++++++++++-
 app/config.py                 |   2 +
 app/main.py                   |  11 ++-
 app/repo/git.py               |   4 +
 app/repo/publisher.py         | 171 ++++++++++++++++++++++++++++++++++
 app/repo/validate.py          |   7 ++
 app/texts.py                  |  16 ++++
 config/texts.yaml             |  25 +++++
 pyproject.toml                |   2 +
 tests/bot/test_commit_push.py |  65 +++++++++++++
 tests/repo/test_publisher.py  | 143 ++++++++++++++++++++++++++++
 11 files changed, 526 insertions(+), 4 deletions(-)
 create mode 100644 app/repo/publisher.py
 create mode 100644 tests/bot/test_commit_push.py
 create mode 100644 tests/repo/test_publisher.py

diff --git a/app/bot/routers/commit.py b/app/bot/routers/commit.py
index 965bd5e..866f8ee 100644
--- a/app/bot/routers/commit.py
+++ b/app/bot/routers/commit.py
@@ -20,10 +20,12 @@ from app.bot.menu import Nav, NavAction
 from app.db.models import ChangeOp, User
 from app.repo.drafts import DraftFull, DraftService, DraftView
 from app.repo.git import Entry, GitError, UploadsRepo
+from app.repo.publisher import Publisher, PushResult, PushStatus
 from app.repo.validate import (
     MAX_FILE_BYTES,
     ValidationError,
     check_content,
+    check_message,
     check_name,
     diff_stat,
     is_protected,
@@ -53,6 +55,10 @@ class Act(StrEnum):
     UNSTAGE = "x"
     FORCE = "y"
     FIX = "z"
+    MESSAGE = "m"
+    PUSH = "ps"
+    PUSH_GO = "pg"
+    PUSH_FORCE = "pf"
 
 
 class CommitCb(CallbackData, prefix="c"):
@@ -66,6 +72,7 @@ class Flow(StatesGroup):
     dir_name = State()
     content = State()
     syntax = State()
+    message = State()
 
 
 class Mark(StrEnum):
@@ -201,7 +208,9 @@ def to_dir_keyboard(texts: Texts) -> InlineKeyboardMarkup:
     return kb.as_markup()
 
 
-def build_router(texts: Texts, repo: UploadsRepo, drafts: DraftService) -> Router:
+def build_router(
+    texts: Texts, repo: UploadsRepo, drafts: DraftService, publisher: Publisher, commit_url_template: str = ""
+) -> Router:
     router = Router(name="commit")
     t = texts.commit
 
@@ -236,15 +245,59 @@ def build_router(texts: Texts, repo: UploadsRepo, drafts: DraftService) -> Route
             ops = {ChangeOp.ADD: t.op_add, ChangeOp.MODIFY: t.op_modify, ChangeOp.DELETE: t.op_delete}
             lines = [t.draft_title.format(count=len(changes)), ""]
             lines += [f"{ops[c.op]}  /{c.path}" for c in changes]
+            message = draft.message if draft else None
+            lines += ["", t.message_current.format(message=message) if message else t.message_missing]
             text = "\n".join(lines)
             for i, c in enumerate(changes):
                 kb.button(
                     text=t.unstage.format(name=c.path.rsplit("/", 1)[-1]), callback_data=CommitCb(a=Act.UNSTAGE, i=i)
                 )
+        if changes:
+            kb.button(text=t.message_button, callback_data=CommitCb(a=Act.MESSAGE))
+            if draft and draft.message:
+                kb.button(text=t.push_button, callback_data=CommitCb(a=Act.PUSH))
         kb.button(text=t.to_dir, callback_data=CommitCb(a=Act.TO_DIR))
         kb.adjust(1)
         return text, kb.as_markup()
 
+    def summary(draft: DraftView) -> str:
+        ops = {ChangeOp.ADD: t.op_add, ChangeOp.MODIFY: t.op_modify, ChangeOp.DELETE: t.op_delete}
+        return "\n".join(f"{ops[c.op]}  /{c.path}" for c in draft.changes)
+
+    async def do_push(msg: Message, state: FSMContext, member: User, *, overwrite: bool) -> None:
+        draft = await drafts.get(member.tg_id)
+        if draft is None or not draft.changes or not draft.message:
+            text, kb = await draft_screen(state, member.tg_id)
+            await msg.edit_text(text, reply_markup=kb)
+            return
+        await msg.edit_text(t.pushing)
+        result: PushResult = await publisher.push(member, draft, draft.message, overwrite=overwrite)
+        match result.status:
+            case PushStatus.OK:
+                assert result.sha is not None
+                first_line = draft.message.splitlines()[0]
+                lines = [t.pushed.format(sha=result.sha[:7], message=first_line)]
+                if commit_url_template:
+                    lines.append(commit_url_template.format(sha=result.sha))
+                lines.append(t.ci_pending)
+                await msg.edit_text("\n".join(lines))
+                await publisher.record(member, result, draft.message, draft, msg.chat.id, msg.message_id)
+                await drafts.clear(member.tg_id)
+                await state.update_data(commit_virtual=[])
+            case PushStatus.CONFLICT:
+                builder = InlineKeyboardBuilder()
+                builder.button(text=t.overwrite, callback_data=CommitCb(a=Act.PUSH_FORCE))
+                builder.button(text=texts.menu.cancel, callback_data=CommitCb(a=Act.DRAFT))
+                paths = "\n".join(f"/{p}" for p in result.conflicts)
+                await msg.edit_text(t.conflict.format(paths=paths), reply_markup=builder.as_markup())
+            case PushStatus.EMPTY:
+                await drafts.clear(member.tg_id)
+                await msg.edit_text(t.push_empty)
+            case PushStatus.LIMIT:
+                await msg.edit_text(t.push_limit, reply_markup=to_dir_keyboard(texts))
+            case PushStatus.FAILED:
+                await msg.edit_text(t.push_failed, reply_markup=to_dir_keyboard(texts))
+
     async def file_card(user_id: int, path: str, size: int, mark: Mark) -> str:
         card = t.file_card.format(path=path, size=human_size(size))
         if mark is Mark.NEW:
@@ -411,6 +464,23 @@ def build_router(texts: Texts, repo: UploadsRepo, drafts: DraftService) -> Route
                         base64.b64decode(pending),
                     )
                     return
+                case Act.MESSAGE:
+                    await state.set_state(Flow.message)
+                    await msg.edit_text(t.ask_message, reply_markup=to_dir_keyboard(texts))
+                case Act.PUSH:
+                    draft = await drafts.get(uid)
+                    if draft is None or not draft.changes or not draft.message:
+                        await query.answer()
+                        return
+                    builder = InlineKeyboardBuilder()
+                    builder.button(text=t.push_go, callback_data=CommitCb(a=Act.PUSH_GO))
+                    builder.button(text=texts.menu.back, callback_data=CommitCb(a=Act.DRAFT))
+                    confirm = t.push_confirm.format(summary=summary(draft), message=draft.message)
+                    await msg.edit_text(confirm, reply_markup=builder.as_markup())
+                case Act.PUSH_GO | Act.PUSH_FORCE:
+                    await query.answer()
+                    await do_push(msg, state, member, overwrite=callback_data.a is Act.PUSH_FORCE)
+                    return
                 case Act.FIX:
                     await state.set_state(Flow.content)
                     await state.update_data(commit_pending=None)
@@ -470,6 +540,18 @@ def build_router(texts: Texts, repo: UploadsRepo, drafts: DraftService) -> Route
         text, kb = await dir_screen(state, member.tg_id, path, 0)
         await message.answer(text, reply_markup=kb)
 
+    @router.message(Flow.message, F.text)
+    async def got_message(message: Message, state: FSMContext, member: User) -> None:
+        try:
+            text = check_message(message.text or "")
+        except ValidationError:
+            await message.answer(t.bad_message)
+            return
+        await drafts.set_message(member.tg_id, text)
+        await state.set_state(None)
+        screen, kb = await draft_screen(state, member.tg_id)
+        await message.answer(screen, reply_markup=kb)
+
     @router.message(Flow.content, F.text | F.document)
     async def got_content(message: Message, state: FSMContext, member: User, bot: Bot) -> None:
         data = await state.get_data()
diff --git a/app/config.py b/app/config.py
index 0f0fe45..689f438 100644
--- a/app/config.py
+++ b/app/config.py
@@ -74,6 +74,8 @@ class GitSettings(BaseSettings):
     # 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"
+    # Web link to a commit in the uploads repo, e.g. https://sourcecraft.dev/{repo}/commit/{sha}; empty — no link
+    commit_url_template: str = ""
     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)
diff --git a/app/main.py b/app/main.py
index d0a4d49..789e390 100644
--- a/app/main.py
+++ b/app/main.py
@@ -19,19 +19,24 @@ from app.health import heartbeat
 from app.logs_setup import setup_logging
 from app.repo.drafts import DraftService
 from app.repo.git import UploadsRepo
+from app.repo.publisher import Publisher
 from app.texts import Texts, load_texts
 
 log = logging.getLogger("tgit")
 
 
-def build_dispatcher(texts: Texts, sessions: SessionMaker, access: AccessService, repo: UploadsRepo) -> Dispatcher:
+def build_dispatcher(
+    texts: Texts, sessions: SessionMaker, access: AccessService, repo: UploadsRepo, commit_url_template: str = ""
+) -> 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, DraftService(sessions)))
+    dp.include_router(
+        commit.build_router(texts, repo, DraftService(sessions), Publisher(repo, sessions), commit_url_template)
+    )
     dp.include_router(common.build_router(texts, access))
     return dp
 
@@ -43,7 +48,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, UploadsRepo(settings.git))
+    dp = build_dispatcher(texts, sessions, access, UploadsRepo(settings.git), settings.git.commit_url_template)
     rt = settings.runtime
     background = [
         asyncio.create_task(heartbeat(rt.heartbeat_file, rt.heartbeat_interval)),
diff --git a/app/repo/git.py b/app/repo/git.py
index 38de956..f1bfeb9 100644
--- a/app/repo/git.py
+++ b/app/repo/git.py
@@ -52,6 +52,10 @@ class UploadsRepo:
         self._fetched_at: float | None = None
         self._key_path = self._materialize_key()
 
+    @property
+    def branch(self) -> str:
+        return self._s.branch
+
     @property
     def ref(self) -> str:
         return f"origin/{self._s.branch}"
diff --git a/app/repo/publisher.py b/app/repo/publisher.py
new file mode 100644
index 0000000..08dcfc5
--- /dev/null
+++ b/app/repo/publisher.py
@@ -0,0 +1,171 @@
+"""Turns a member's draft into one commit on the uploads repo's main branch (SPEC C-20…C-25, ARCHITECTURE §2.3).
+
+Pushes are serialized with a lock: two members pushing at once never fight over the shared working tree.
+"""
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import StrEnum
+from pathlib import Path
+
+from sqlalchemy import func, select
+
+from app.db.models import ChangeOp, Push, User, utcnow
+from app.db.session import SessionMaker
+from app.repo.drafts import DraftView
+from app.repo.git import GitError, UploadsRepo
+
+log = logging.getLogger(__name__)
+
+BOT_NAME = "tgit-bot"
+BOT_EMAIL = "tgit-bot@users.noreply.tgit"
+PUSHES_PER_HOUR = 20
+PUSH_ATTEMPTS = 3
+
+
+class PushStatus(StrEnum):
+    OK = "ok"
+    CONFLICT = "conflict"  # someone changed the same files in main since the draft began
+    EMPTY = "empty"  # the draft matches main already
+    LIMIT = "limit"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class PushResult:
+    status: PushStatus
+    sha: str | None = None
+    conflicts: list[str] = field(default_factory=list)
+
+
+class Publisher:
+    def __init__(
+        self,
+        repo: UploadsRepo,
+        sessions: SessionMaker,
+        clock: Callable[[], datetime] = utcnow,
+        before_push: Callable[[], Awaitable[None]] | None = None,  # test hook: simulate a concurrent push
+    ) -> None:
+        self._repo = repo
+        self._sessions = sessions
+        self._clock = clock
+        self._before_push = before_push
+        self._lock = asyncio.Lock()
+
+    async def push(self, member: User, draft: DraftView, message: str, *, overwrite: bool = False) -> PushResult:
+        if await self._pushes_last_hour(member.tg_id) >= PUSHES_PER_HOUR:
+            return PushResult(PushStatus.LIMIT)
+        async with self._lock:
+            try:
+                return await self._push(member, draft, message, overwrite)
+            except GitError:
+                log.exception("push failed")
+                await self._reset()
+                return PushResult(PushStatus.FAILED)
+
+    async def record(
+        self, member: User, result: PushResult, message: str, draft: DraftView, chat_id: int, message_id: int
+    ) -> None:
+        assert result.sha is not None
+        async with self._sessions.begin() as s:
+            s.add(
+                Push(
+                    user_id=member.tg_id,
+                    sha=result.sha,
+                    message=message,
+                    paths=[c.path for c in draft.changes],
+                    chat_id=chat_id,
+                    message_id=message_id,
+                    created_at=self._clock(),
+                )
+            )
+
+    async def _push(self, member: User, draft: DraftView, message: str, overwrite: bool) -> PushResult:
+        repo = self._repo
+        await repo.refresh(force=True)
+        if not overwrite:
+            conflicts = await self._conflicts(draft)
+            if conflicts:
+                return PushResult(PushStatus.CONFLICT, conflicts=conflicts)
+
+        await self._reset()
+        self._apply(draft)
+        await repo.git("add", "-A")
+        try:
+            await repo.git("diff", "--cached", "--quiet")
+            return PushResult(PushStatus.EMPTY)  # exit 0: nothing staged
+        except GitError:
+            pass  # exit 1: there are changes
+
+        handle = f"@{member.username}" if member.username else member.full_name
+        full_message = f"{message.strip()}\n\nTelegram-User: {handle} ({member.tg_id})"
+        await repo.git(
+            "-c", f"user.name={BOT_NAME}", "-c", f"user.email={BOT_EMAIL}", "commit", "-q", "-m", full_message
+        )
+
+        branch = repo.branch
+        for attempt in range(1, PUSH_ATTEMPTS + 1):
+            if self._before_push is not None:
+                await self._before_push()
+            try:
+                await repo.git("push", "-q", "origin", f"HEAD:{branch}")
+                break
+            except GitError:
+                if attempt == PUSH_ATTEMPTS:
+                    raise
+                log.info("push rejected, rebasing (attempt %d)", attempt)
+                await repo.git("fetch", "-q", "origin")
+                try:
+                    await repo.git(
+                        "-c", f"user.name={BOT_NAME}", "-c", f"user.email={BOT_EMAIL}", "rebase", "-q", repo.ref
+                    )
+                except GitError:
+                    await repo.git("rebase", "--abort")
+                    return PushResult(PushStatus.CONFLICT, conflicts=await self._conflicts(draft))
+        sha = (await repo.git("rev-parse", "HEAD")).decode().strip()
+        return PushResult(PushStatus.OK, sha=sha)
+
+    async def _conflicts(self, draft: DraftView) -> list[str]:
+        try:
+            out = await self._repo.git("diff", "--name-only", draft.base_sha, self._repo.ref)
+        except GitError:
+            return [c.path for c in draft.changes]  # base unknown (e.g. history rewritten): be safe
+        changed = set(out.decode().splitlines())
+        return [c.path for c in draft.changes if c.path in changed]
+
+    async def _reset(self) -> None:
+        repo = self._repo
+        await repo.git("checkout", "-q", "-B", repo.branch, repo.ref)
+        await repo.git("reset", "-q", "--hard", repo.ref)
+        await repo.git("clean", "-q", "-fdx")
+
+    def _apply(self, draft: DraftView) -> None:
+        root = self._repo.path.resolve()
+        for change in draft.changes:
+            target = (root / change.path).resolve()
+            if root not in target.parents:  # validated earlier; this is the last line of defence
+                raise GitError(f"path escapes the repo: {change.path}")
+            if change.op is ChangeOp.DELETE:
+                target.unlink(missing_ok=True)
+                _prune_empty_dirs(target.parent, root)
+            else:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(change.content or b"")
+
+    async def _pushes_last_hour(self, user_id: int) -> int:
+        async with self._sessions() as s:
+            count = await s.scalar(
+                select(func.count())
+                .select_from(Push)
+                .where(Push.user_id == user_id, Push.created_at > self._clock() - timedelta(hours=1))
+            )
+            return count or 0
+
+
+def _prune_empty_dirs(directory: Path, root: Path) -> None:
+    while directory != root and directory.is_dir() and not any(directory.iterdir()):
+        directory.rmdir()
+        directory = directory.parent
diff --git a/app/repo/validate.py b/app/repo/validate.py
index e0a7447..9c28f28 100644
--- a/app/repo/validate.py
+++ b/app/repo/validate.py
@@ -74,3 +74,10 @@ def diff_stat(old: str, new: str) -> tuple[int, int]:
         elif line.startswith("- "):
             removed += 1
     return added, removed
+
+
+def check_message(message: str) -> str:
+    message = message.strip()
+    if not 1 <= len(message) <= 200 or len(message.splitlines()[0]) > 72:
+        raise ValidationError("message")
+    return message
diff --git a/app/texts.py b/app/texts.py
index 53d7f79..803e65a 100644
--- a/app/texts.py
+++ b/app/texts.py
@@ -104,6 +104,22 @@ class CommitTexts(_Strict):
     op_add: str
     op_modify: str
     op_delete: str
+    message_button: str
+    message_current: str
+    message_missing: str
+    ask_message: str
+    bad_message: str
+    push_button: str
+    push_confirm: str
+    push_go: str
+    pushing: str
+    pushed: str
+    ci_pending: str
+    conflict: str
+    overwrite: str
+    push_empty: str
+    push_limit: str
+    push_failed: str
 
 
 class Texts(_Strict):
diff --git a/config/texts.yaml b/config/texts.yaml
index 8dcd4b1..7df9dd1 100644
--- a/config/texts.yaml
+++ b/config/texts.yaml
@@ -107,3 +107,28 @@ commit:
   op_add: "A"
   op_modify: "M"
   op_delete: "D"
+  message_button: "💬 Сообщение коммита"
+  message_current: "💬 {message}"
+  message_missing: "💬 Сообщение коммита не задано."
+  ask_message: "Сообщение коммита: до 200 символов, первая строка — до 72."
+  bad_message: "Сообщение: 1–200 символов, первая строка — до 72. Пришлите другое."
+  push_button: "🚀 Push"
+  push_confirm: |-
+    Запушить в main?
+
+    {summary}
+
+    💬 {message}
+  push_go: "✅ Запушить"
+  pushing: "⏳ Пушу…"
+  pushed: "✅ Запушено: {sha} — {message}"
+  ci_pending: "⏳ CI…"
+  conflict: |-
+    ⚠️ Пока вы готовили черновик, в main изменились те же файлы:
+    {paths}
+
+    Перезаписать их вашей версией?
+  overwrite: "Перезаписать"
+  push_empty: "В main уже всё так же — коммитить нечего. Черновик очищен."
+  push_limit: "Лимит — 20 пушей в час. Попробуйте позже."
+  push_failed: "Не удалось запушить: репозиторий недоступен. Черновик сохранён — попробуйте позже."
diff --git a/pyproject.toml b/pyproject.toml
index dee183b..dd0ca9b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -42,6 +42,8 @@ extend-exclude = [".claude", "docs"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP", "SIM", "ASYNC", "RUF"]
+# Russian UI texts, commit messages and comments are normal here, not homoglyph attacks
+ignore = ["RUF001", "RUF002", "RUF003"]
 
 [tool.mypy]
 python_version = "3.12"
diff --git a/tests/bot/test_commit_push.py b/tests/bot/test_commit_push.py
new file mode 100644
index 0000000..158e7bc
--- /dev/null
+++ b/tests/bot/test_commit_push.py
@@ -0,0 +1,65 @@
+from pathlib import Path
+
+import pytest
+from aiogram.methods import EditMessageText, SendMessage
+from aiogram.types import InlineKeyboardMarkup
+
+from app.access.service import AccessService
+from app.bot.routers.commit import Act, CommitCb
+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, git
+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, "https://example.test/commit/{sha}"))
+
+
+def cb(action: Act, i: int = 0) -> str:
+    return CommitCb(a=action, i=i).pack()
+
+
+def labels(markup: object) -> list[str]:
+    assert isinstance(markup, InlineKeyboardMarkup)
+    return [b.text for row in markup.inline_keyboard for b in row]
+
+
+async def test_message_then_push_lands_in_remote(tg: TgClient, texts: Texts, remote: Path, tmp_path: Path) -> None:
+    t = texts.commit
+    await tg.send(ADMIN, texts.menu.commit)
+    await tg.press(ADMIN, cb(Act.NEW_FILE))
+    await tg.send(ADMIN, "notes.txt")
+    await tg.send(ADMIN, "привет из телеграма")
+    await tg.press(ADMIN, cb(Act.DRAFT))
+    draft = tg.session.sent(EditMessageText)[-1]
+    assert t.message_missing in draft.text and t.push_button not in labels(draft.reply_markup)
+
+    await tg.press(ADMIN, cb(Act.MESSAGE))
+    await tg.send(ADMIN, "x" * 80)  # first line too long
+    assert tg.session.sent(SendMessage)[-1].text == t.bad_message
+    await tg.send(ADMIN, "docs: заметки")
+    with_message = tg.session.sent(SendMessage)[-1]
+    assert t.message_current.format(message="docs: заметки") in with_message.text
+    assert t.push_button in labels(with_message.reply_markup)
+
+    await tg.press(ADMIN, cb(Act.PUSH))
+    assert tg.session.sent(EditMessageText)[-1].text.startswith("Запушить в main?")
+    await tg.press(ADMIN, cb(Act.PUSH_GO))
+
+    pushing, done = tg.session.sent(EditMessageText)[-2:]
+    assert pushing.text == t.pushing
+    assert done.text.startswith("✅ Запушено: ") and "docs: заметки" in done.text
+    assert "https://example.test/commit/" in done.text and done.text.endswith(t.ci_pending)
+
+    clone = tmp_path / "verify"
+    git(tmp_path, "clone", "-q", str(remote), str(clone))
+    assert (clone / "notes.txt").read_text(encoding="utf-8") == "привет из телеграма"
+
+    # the draft is gone after a push
+    tg.session.requests.clear()
+    await tg.send(ADMIN, texts.menu.commit)
+    assert not any(label.startswith("🧾") for label in labels(tg.session.sent(SendMessage)[-1].reply_markup))
diff --git a/tests/repo/test_publisher.py b/tests/repo/test_publisher.py
new file mode 100644
index 0000000..bdf7e08
--- /dev/null
+++ b/tests/repo/test_publisher.py
@@ -0,0 +1,143 @@
+from datetime import timedelta
+from pathlib import Path
+
+import pytest
+from sqlalchemy import select
+
+from app.access.service import AccessService
+from app.db.models import ChangeOp, Push, User, utcnow
+from app.db.session import SessionMaker
+from app.repo.drafts import Change, DraftView
+from app.repo.git import UploadsRepo
+from app.repo.publisher import PUSHES_PER_HOUR, Publisher, PushStatus
+from tests.conftest import ADMIN, git
+
+
+@pytest.fixture
+async def member(access: AccessService) -> User:
+    user = await access.get_member(ADMIN)
+    assert user is not None
+    return user
+
+
+def remote_log(remote: Path, tmp_path: Path, name: str = "check") -> tuple[Path, str]:
+    clone = tmp_path / name
+    git(tmp_path, "clone", "-q", str(remote), str(clone))
+    return clone, git(clone, "log", "-1", "--format=%an <%ae>%n%B")
+
+
+def foreign_commit(remote: Path, tmp_path: Path, path: str, text: str, name: str) -> None:
+    other = tmp_path / name
+    git(tmp_path, "clone", "-q", str(remote), str(other))
+    target = other / path
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8")
+    git(other, "add", "-A")
+    git(other, "commit", "-q", "-m", f"foreign {path}")
+    git(other, "push", "-q", "origin", "main")
+
+
+async def draft_on(repo: UploadsRepo, *changes: Change) -> DraftView:
+    await repo.refresh(force=True)
+    return DraftView(base_sha=await repo.head(), message=None, changes=list(changes))
+
+
+async def test_push_applies_changes_with_trailer(
+    repo: UploadsRepo, sessions: SessionMaker, member: User, remote: Path, tmp_path: Path
+) -> None:
+    draft = await draft_on(
+        repo,
+        Change("services/hello/utils.py", ChangeOp.ADD, b"X = 1\n"),
+        Change("services/hello/main.py", ChangeOp.MODIFY, b"print('v2')\n"),
+        Change("docs/logo.bin", ChangeOp.DELETE, None),
+        Change("docs/мои заметки.md", ChangeOp.DELETE, None),
+    )
+    publisher = Publisher(repo, sessions)
+
+    result = await publisher.push(member, draft, "feat: v2\n\nподробности")
+
+    assert result.status is PushStatus.OK and result.sha is not None
+    clone, log = remote_log(remote, tmp_path)
+    assert log.startswith("tgit-bot \nfeat: v2\n\nподробности\n\nTelegram-User: ")
+    assert f"({ADMIN})" in log
+    assert (clone / "services/hello/utils.py").read_text() == "X = 1\n"
+    assert (clone / "services/hello/main.py").read_text() == "print('v2')\n"
+    assert not (clone / "docs").exists()  # both files gone → the folder is gone too
+    assert git(clone, "rev-parse", "HEAD").strip() == result.sha
+
+
+async def test_nothing_to_commit(repo: UploadsRepo, sessions: SessionMaker, member: User) -> None:
+    draft = await draft_on(repo, Change("README.md", ChangeOp.MODIFY, b"# uploads\n"))
+
+    assert (await Publisher(repo, sessions).push(member, draft, "noop")).status is PushStatus.EMPTY
+
+
+async def test_conflict_then_overwrite(
+    repo: UploadsRepo, sessions: SessionMaker, member: User, remote: Path, tmp_path: Path
+) -> None:
+    draft = await draft_on(repo, Change("README.md", ChangeOp.MODIFY, b"mine\n"))
+    foreign_commit(remote, tmp_path, "README.md", "theirs\n", "other")
+    publisher = Publisher(repo, sessions)
+
+    conflict = await publisher.push(member, draft, "edit readme")
+    assert conflict.status is PushStatus.CONFLICT and conflict.conflicts == ["README.md"]
+
+    forced = await publisher.push(member, draft, "edit readme", overwrite=True)
+    assert forced.status is PushStatus.OK
+    clone, _ = remote_log(remote, tmp_path)
+    assert (clone / "README.md").read_text() == "mine\n"
+
+
+async def test_unrelated_change_in_main_is_not_a_conflict(
+    repo: UploadsRepo, sessions: SessionMaker, member: User, remote: Path, tmp_path: Path
+) -> None:
+    draft = await draft_on(repo, Change("a.txt", ChangeOp.ADD, b"a"))
+    foreign_commit(remote, tmp_path, "b.txt", "b", "other")
+
+    assert (await Publisher(repo, sessions).push(member, draft, "add a")).status is PushStatus.OK
+    clone, _ = remote_log(remote, tmp_path)
+    assert (clone / "a.txt").exists() and (clone / "b.txt").exists()
+
+
+async def test_rejected_push_is_rebased(
+    repo: UploadsRepo, sessions: SessionMaker, member: User, remote: Path, tmp_path: Path
+) -> None:
+    raced = False
+
+    async def someone_pushes_first() -> None:
+        nonlocal raced
+        if not raced:
+            raced = True
+            foreign_commit(remote, tmp_path, "race.txt", "r", "racer")
+
+    draft = await draft_on(repo, Change("mine.txt", ChangeOp.ADD, b"m"))
+    result = await Publisher(repo, sessions, before_push=someone_pushes_first).push(member, draft, "add mine")
+
+    assert result.status is PushStatus.OK and raced
+    clone, log = remote_log(remote, tmp_path)
+    assert "add mine" in log and (clone / "race.txt").exists() and (clone / "mine.txt").exists()
+
+
+async def test_path_escape_is_refused(repo: UploadsRepo, sessions: SessionMaker, member: User, tmp_path: Path) -> None:
+    draft = await draft_on(repo, Change("../evil.txt", ChangeOp.ADD, b"x"))
+
+    assert (await Publisher(repo, sessions).push(member, draft, "evil")).status is PushStatus.FAILED
+    assert not (tmp_path / "evil.txt").exists()
+
+
+async def test_rate_limit_and_record(repo: UploadsRepo, sessions: SessionMaker, member: User) -> None:
+    publisher = Publisher(repo, sessions)
+    draft = await draft_on(repo, Change("x.txt", ChangeOp.ADD, b"x"))
+    result = await publisher.push(member, draft, "x")
+    await publisher.record(member, result, "x", draft, chat_id=ADMIN, message_id=77)
+
+    async with sessions() as s:
+        push = await s.scalar(select(Push))
+        assert push is not None and push.sha == result.sha and push.paths == ["x.txt"] and push.message_id == 77
+        for i in range(PUSHES_PER_HOUR):
+            s.add(
+                Push(user_id=ADMIN, sha=f"{i:040d}", message="m", chat_id=1, created_at=utcnow() - timedelta(minutes=1))
+            )
+        await s.commit()
+
+    assert (await publisher.push(member, draft, "y")).status is PushStatus.LIMIT