ktalk-cli 1.0.0__py3-none-any.whl

ktalk_cli/cli_meeting.py

@@ -0,0 +1,68 @@
+"""FR-13 CLI: `create-meeting-preview`/`cancel-meeting-preview` — предпросмотр без сети.
+
+Подтверждающие команды переехали в `cli_meeting_confirm.py` (ADR-016 §6): обе ветки
+подтверждения в одном файле с аргументами перевалили бы порог гейта C13 (350 строк).
+Общие аргументы и печать ошибок — `cli_meeting_args.py`.
+
+ADR-016 §2: `confirmation_id` снова выводится в `--json`. Решение ADR-015 его не
+выводить следовало из хранилища в памяти («не переживает границу процессов») и
+отменено вместе с причиной — хранилище персистентно, и именно id связывает
+предъявленное оператору тело с фактической записью.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ktalk_cli.cli_meeting_args import (
+    add_cancel_args,
+    add_meeting_args,
+    meeting_kwargs,
+    print_error,
+)
+from ktalk_cli.confirmation import ConfirmationStore
+from ktalk_cli.formatters import (
+    format_cancel_preview,
+    format_meeting_preview,
+    format_raw,
+    render_tool_output,
+)
+from ktalk_cli.meeting_body import MissingFieldError, TimezoneFormatError
+from ktalk_cli.meeting_cancel import CancelPreviewService
+from ktalk_cli.meeting_scheduling import PreviewService
+
+
+def register_subparsers(sub) -> None:
+    p_create_preview = sub.add_parser("create-meeting-preview", help="Предпросмотр встречи (FR-13)")
+    add_meeting_args(p_create_preview)
+    p_create_preview.add_argument("--json", action="store_true")
+
+    p_cancel_preview = sub.add_parser(
+        "cancel-meeting-preview", help="Предпросмотр отмены (ADR-011)"
+    )
+    add_cancel_args(p_cancel_preview)
+    p_cancel_preview.add_argument("--json", action="store_true")
+
+
+def cmd_create_meeting_preview(_reg, args: argparse.Namespace) -> int:
+    """Без сети — только валидация и предпросмотр."""
+    service = PreviewService(ConfirmationStore())
+    try:
+        body, confirmation_id = service.preview(**meeting_kwargs(args))
+    except (MissingFieldError, TimezoneFormatError) as exc:
+        print_error(str(exc))
+        return 1
+    data = {"body": body, "confirmation_id": confirmation_id}
+    print(format_raw(data) if args.json else render_tool_output(data, "markdown",
+                                                               format_meeting_preview))
+    return 0
+
+
+def cmd_cancel_meeting_preview(_reg, args: argparse.Namespace) -> int:
+    """Без сети — только предпросмотр (ADR-011-spec §4)."""
+    service = CancelPreviewService(ConfirmationStore())
+    payload, confirmation_id = service.preview(id=args.id, reason=args.reason)
+    data = {"payload": payload, "confirmation_id": confirmation_id}
+    print(format_raw(data) if args.json else render_tool_output(data, "markdown",
+                                                               format_cancel_preview))
+    return 0

ktalk_cli/cli_meeting_args.py

@@ -0,0 +1,123 @@
+"""Общие аргументы и вывод ошибок пишущих команд встреч (ADR-016 §6).
+
+Выделено из `cli_meeting.py` при расщеплении на предпросмотр и подтверждение:
+общий у команд именно набор аргументов, а не операция, поэтому расщепление прошло
+по каналу («предпросмотр / подтверждение»), а не по операции.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ktalk_cli.config import redact_secrets
+
+
+def tri_bool(value: str) -> bool:
+    """NFR-9: явный `true|false`, не `store_true` — `store_true` дал бы молчаливый
+    `False` при отсутствии флага, ровно тихий дефолт, который NFR-9 запрещает."""
+    lowered = value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    raise argparse.ArgumentTypeError(f'Ожидается "true" или "false", получено: {value!r}')
+
+
+def add_meeting_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--subject", default=None)
+    parser.add_argument("--start", default=None)
+    parser.add_argument("--end", default=None)
+    parser.add_argument(
+        "--timezone",
+        default=None,
+        help="Формат GMT±N, пример: GMT+3 (единственная подтверждённая форма, FR-40)",
+    )
+    parser.add_argument("--room-name", default=None)
+    # ADR-009 §5: `--required-user-key` (логин) переименован в `--required-attendee-key`
+    # (числовой id) — резолюция логина в id не реализуется этим ADR, оператор
+    # передаёт значение явно (см. Бриф для Dev spec §5).
+    parser.add_argument("--required-attendee-key", action="append", default=None)
+    parser.add_argument(
+        "--no-required-attendees",
+        action="store_true",
+        help="Явное «без обязательных участников» (не то же самое, что отсутствие флага)",
+    )
+    parser.add_argument("--description", default=None)
+    parser.add_argument("--enable-auto-recording", type=tri_bool, default=None)
+    parser.add_argument("--pin-code", default=None)
+    parser.add_argument(
+        "--no-pin-code",
+        action="store_true",
+        help='Явное «без PIN» (JSON null) — не то же самое, что отсутствие флага (ADR-009 §2)',
+    )
+    parser.add_argument("--allow-anonymous", type=tri_bool, default=None)
+    parser.add_argument(
+        "--anonymous-access-expiration",
+        default=None,
+        help=(
+            "Обязателен, если --allow-anonymous true (ADR-009 §3 — нет вычисляемого "
+            "дефолта, значение указывается явно)"
+        ),
+    )
+
+
+def add_cancel_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--id",
+        required=True,
+        help="Base64 id встречи (Ф-56, из ответа create-meeting-confirm или чтения "
+        "календаря); не хранится проектом",
+    )
+    parser.add_argument(
+        "--reason",
+        default="",
+        help='Причина отмены (опционально, дефолт "" — единственный подтверждённый '
+        "рабочий образец, Ф-50)",
+    )
+
+
+def required_attendee_keys(args: argparse.Namespace) -> list[str] | None:
+    """`--no-required-attendees` побеждает при одновременной передаче обоих
+    флагов — порядок не специфицирован спекой, зафиксирован здесь и тестом."""
+    if args.no_required_attendees:
+        return []
+    return args.required_attendee_key
+
+
+def meeting_kwargs(args: argparse.Namespace) -> dict:
+    return {
+        "subject": args.subject,
+        "start": args.start,
+        "end": args.end,
+        "timezone": args.timezone,
+        "room_name": args.room_name,
+        "required_attendee_keys": required_attendee_keys(args),
+        "description": args.description,
+        "enable_auto_recording": args.enable_auto_recording,
+        "pin_code": args.pin_code,
+        "pin_code_explicit_none": args.no_pin_code,
+        "allow_anonymous": args.allow_anonymous,
+        "anonymous_access_expiration": args.anonymous_access_expiration,
+    }
+
+
+# DEV-008: сентинел, а не `None` по умолчанию — различает "response_body не
+# прикреплён вовсе" (нет ответа сервера, печатать нечего) и "прикреплён пустой"
+# (тело ответа сервера фактически пустое — это наблюдение о контуре, не потеря
+# кода). Оба раньше давали одно и то же "ничего не печатать".
+NO_RESPONSE_BODY = object()
+
+
+def print_error(message: str, response_body: object = NO_RESPONSE_BODY) -> None:
+    """ADR-008 §3: тело ответа сервера (если было прикреплено к исключению) печатается
+    вместе с основным текстом, тем же проходом `redact_secrets` — новой точки
+    маскирования не вводится. Пустое тело печатается явно как факт (DEV-008), не
+    опускается."""
+    if response_body is NO_RESPONSE_BODY:
+        text = message
+    elif response_body:
+        text = f"{message}\nТело ответа сервера: {response_body}"
+    else:
+        text = f"{message}\nТело ответа сервера: (пусто)"
+    print(f"Ошибка: {redact_secrets(text)}", file=sys.stderr)

ktalk_cli/cli_meeting_confirm.py

@@ -0,0 +1,256 @@
+"""ADR-016 §1: `create-meeting-confirm`/`cancel-meeting-confirm` — два канала.
+
+| Канал | Признак | Требуется | Не требуется |
+|---|---|---|---|
+| `tty` | `isatty()` на stdin и stdout | слово подтверждения | санкция, `--confirmation-id` |
+| `sanctioned` | терминала нет | санкция + валидный `--confirmation-id` | слово подтверждения |
+
+Канал выбирается по факту наличия терминала, не флагом: флаг был бы параметром,
+который вызывающий выставляет сам, — ровно та ошибка, которую ADR-005 отклонил для
+подтверждения-параметра.
+
+Порядок проверок в санкционном канале: санкция -> подтверждение -> журнал -> сеть.
+Санкция раньше подтверждения намеренно: иначе перебор `--confirmation-id` различал
+бы состояния санкции по коду возврата.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+
+from ktalk_cli import write_sanction
+from ktalk_cli.cli_meeting_args import (
+    NO_RESPONSE_BODY,
+    add_cancel_args,
+    add_meeting_args,
+    meeting_kwargs,
+    print_error,
+)
+from ktalk_cli.client import KTalkClient
+from ktalk_cli.config import Settings
+from ktalk_cli.confirmation import ConfirmationStore
+from ktalk_cli.formatters import (
+    format_cancel_preview,
+    format_meeting_preview,
+    render_tool_output,
+)
+from ktalk_cli.meeting_body import MissingFieldError, TimezoneFormatError, canonical_body_hash
+from ktalk_cli.meeting_cancel import CancelPreviewService, build_cancel_confirmation_payload
+from ktalk_cli.meeting_scheduling import PreviewService, cancel_meeting, create_meeting
+from ktalk_cli.write_journal import JournalUnavailableError, append_attempt, append_outcome
+
+# Слово подтверждения не зафиксировано ни спекой, ни ADR — рабочая гипотеза
+# QA-author (at-design.md «Допущения»), подтверждена здесь как решение Dev.
+_CONFIRM_WORD = "да"
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_NO_SANCTION = 40
+EXIT_SANCTION_EXPIRED = 41
+EXIT_SANCTION_EXHAUSTED = 42
+EXIT_BAD_CONFIRMATION = 44
+
+_SANCTION_EXIT = {
+    "absent": EXIT_NO_SANCTION,
+    "expired": EXIT_SANCTION_EXPIRED,
+    "exhausted": EXIT_SANCTION_EXHAUSTED,
+}
+
+
+def register_subparsers(sub) -> None:
+    # DEV-009 оставлял `*-confirm` без `--json` («их не вызывают программно»).
+    # ADR-016 это отменяет: теперь вызывают, и разбирать надо машиночитаемо.
+    p_create = sub.add_parser("create-meeting-confirm", help="Создать встречу (ADR-016)")
+    add_meeting_args(p_create)
+    _add_confirm_args(p_create)
+
+    p_cancel = sub.add_parser("cancel-meeting-confirm", help="Отменить встречу (ADR-016)")
+    add_cancel_args(p_cancel)
+    _add_confirm_args(p_cancel)
+
+
+def _add_confirm_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--confirmation-id",
+        default=None,
+        help="id из соответствующего *-preview; обязателен вне интерактивного терминала",
+    )
+    parser.add_argument("--json", action="store_true")
+
+
+def _interactive() -> bool:
+    return bool(sys.stdin.isatty() and sys.stdout.isatty())
+
+
+def _ask_confirmation(prompt: str) -> bool:
+    print(f'\nВведите "{_CONFIRM_WORD}" для подтверждения {prompt}: ', end="", flush=True)
+    return sys.stdin.readline().strip().lower() == _CONFIRM_WORD
+
+
+def _authorize(operation: str, args: argparse.Namespace, store, body_hash: str):
+    """Возвращает `(channel, confirmation_id, remaining, exit_code)`; `exit_code`
+    не `None` — отказ, сетевого вызова не будет."""
+    if _interactive():
+        return "tty", None, None, None
+
+    state = write_sanction.read_state(operation)
+    if not state.active:
+        print_error(
+            f"Нет действующей санкции на операцию «{operation}» (состояние: {state.status}). "
+            f"Выдать её может только человек в своём терминале: "
+            f"ktalk sanction grant {operation.replace('_', '-')}",
+        )
+        return "sanctioned", None, None, _SANCTION_EXIT[state.status]
+
+    confirmation_id = args.confirmation_id
+    if not confirmation_id or not store.match(confirmation_id, body_hash):
+        print_error(
+            "Подтверждение недействительно: нужен --confirmation-id из свежего "
+            "*-preview с теми же параметрами (ADR-016 §2)."
+        )
+        return "sanctioned", None, None, EXIT_BAD_CONFIRMATION
+
+    store.consume(confirmation_id)  # до сетевой попытки — повтор требует нового предпросмотра
+    remaining = write_sanction.consume(operation)
+    return "sanctioned", confirmation_id, remaining, None
+
+
+def _report(args: argparse.Namespace, payload: dict, text: str) -> None:
+    if getattr(args, "json", False):
+        print(json.dumps(payload, ensure_ascii=False))
+    else:
+        print(text)
+
+
+def _run_confirm(operation, args, *, preview, formatter, prompt, network, describe) -> int:
+    store = ConfirmationStore()
+    try:
+        body, own_confirmation_id = preview(store)
+    except (MissingFieldError, TimezoneFormatError) as exc:
+        print_error(str(exc))
+        return EXIT_ERROR
+
+    body_hash = canonical_body_hash(body)
+    channel, confirmation_id, remaining, refusal = _authorize(operation, args, store, body_hash)
+    if refusal is not None:
+        return refusal
+
+    # Предпросмотр печатается в обоих каналах: в `tty` — перед вопросом человеку,
+    # в `sanctioned` — как след в выводе команды рядом с журнальной записью.
+    print(render_tool_output({**describe(body), "confirmation_id": own_confirmation_id},
+                             "markdown", formatter))
+    if channel == "tty":
+        if not _ask_confirmation(prompt):
+            print("Отменено — подтверждение не получено.", file=sys.stderr)
+            return EXIT_ERROR
+        if not store.match(own_confirmation_id, body_hash):
+            print_error("Подтверждение истекло или недействительно — начните заново.")
+            return EXIT_BAD_CONFIRMATION
+        store.consume(own_confirmation_id)
+        confirmation_id = own_confirmation_id
+
+    try:
+        append_attempt(
+            operation=operation,
+            channel=channel,
+            confirmation_id=confirmation_id or "",
+            body_sha256=body_hash,
+            body=body,
+            sanction_remaining=remaining,
+        )
+    except JournalUnavailableError as exc:
+        print_error(f"{exc} — запись в контур не выполнена (ADR-016 §5).")
+        return EXIT_ERROR
+
+    try:
+        result = asyncio.run(network(body))
+    except Exception as exc:  # noqa: BLE001 - любая ошибка = "исход неизвестен", без retry
+        status_code = getattr(exc, "status_code", None)
+        _outcome(
+            operation, channel, confirmation_id, body_hash,
+            "failed" if status_code is not None else "unknown", status_code,
+        )
+        _print_failure(args, exc, status_code, operation)
+        return EXIT_ERROR
+
+    _outcome(operation, channel, confirmation_id, body_hash, "ok", 200)
+    _report(args, {"status": "ok", "operation": operation, "result": result},
+            f"{'Встреча создана' if operation == 'create_meeting' else 'Встреча отменена'}: "
+            f"{result.get('id', result) if isinstance(result, dict) else result}")
+    return EXIT_OK
+
+
+def _outcome(operation, channel, confirmation_id, body_hash, result, status_code) -> None:
+    try:
+        append_outcome(
+            operation=operation,
+            channel=channel,
+            confirmation_id=confirmation_id or "",
+            body_sha256=body_hash,
+            result=result,
+            status_code=status_code,
+        )
+    except JournalUnavailableError as exc:
+        # Откатывать нечем — операция уже выполнена; молчать нельзя.
+        print(f"Внимание: исход не записан в журнал ({exc}).", file=sys.stderr)
+
+
+def _print_failure(args, exc, status_code, operation) -> None:
+    base_message = str(exc)
+    if status_code is not None and f"HTTP {status_code}" not in base_message:
+        base_message = f"{base_message} (HTTP {status_code})"
+    command = f"{operation.replace('_meeting', '-meeting').replace('_', '-')}-confirm"
+    message = (
+        f"{base_message} — исход неизвестен, проверьте `ktalk list-calendar` перед "
+        f"повторной попыткой (повторный запуск {command} не выполняет автоматический "
+        "retry, NFR-22; подтверждение и единица бюджета санкции уже потрачены)."
+    )
+    control_probe = getattr(exc, "control_probe", None)
+    if control_probe:
+        message = f"{message}\n{control_probe}"
+    if getattr(args, "json", False):
+        print(json.dumps({"status": "unknown", "operation": operation, "message": message},
+                         ensure_ascii=False))
+    print_error(message, getattr(exc, "response_body", NO_RESPONSE_BODY))
+
+
+async def _create_over_network(body: dict) -> dict:
+    async with KTalkClient.from_settings(Settings()) as client:
+        return await create_meeting(client, body)
+
+
+def cmd_create_meeting_confirm(_reg, args: argparse.Namespace) -> int:
+    service_kwargs = meeting_kwargs(args)
+    return _run_confirm(
+        "create_meeting",
+        args,
+        preview=lambda store: PreviewService(store).preview(**service_kwargs),
+        formatter=format_meeting_preview,
+        prompt="создания встречи",
+        network=_create_over_network,
+        describe=lambda body: {"body": body},
+    )
+
+
+async def _cancel_over_network(id: str, reason: str) -> dict:
+    async with KTalkClient.from_settings(Settings()) as client:
+        return await cancel_meeting(client, id=id, reason=reason)
+
+
+def cmd_cancel_meeting_confirm(_reg, args: argparse.Namespace) -> int:
+    return _run_confirm(
+        "cancel_meeting",
+        args,
+        preview=lambda store: CancelPreviewService(store).preview(id=args.id, reason=args.reason),
+        formatter=format_cancel_preview,
+        prompt="отмены встречи",
+        network=lambda _body: _cancel_over_network(args.id, args.reason),
+        describe=lambda payload: {"payload": payload},
+    )
+
+
+def build_cancel_payload(args: argparse.Namespace) -> dict:
+    return build_cancel_confirmation_payload(id=args.id, reason=args.reason)

ktalk_cli/cli_meetings_read.py

@@ -0,0 +1,115 @@
+"""CLI-эквиваленты оставшихся читающих MCP-инструментов (DEV-002 волны 3, ADR-012
+§2а): `list-archive` (FR-9), `get-chat-messages` (FR-10), `list-calendar` (FR-18),
+`get-room` (FR-17) — те же операции, что `tools_meetings.py`/`tools_rooms.py`,
+вторая обёртка над тем же клиентом/форматтерами.
+
+Все команды — `_REGISTRY_FREE_COMMANDS` (не открывают SQLite, читают только сеть).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from datetime import date
+
+from ktalk_cli.calendar_reader import get_calendar_window
+from ktalk_cli.client import KTalkClient
+from ktalk_cli.config import Settings, redact_secrets
+from ktalk_cli.formatters import (
+    format_archive_list,
+    format_calendar,
+    format_chat_messages,
+    format_room,
+    render_tool_output,
+)
+from ktalk_cli.rooms import get_room
+
+
+def register_subparsers(sub) -> None:
+    p_arch = sub.add_parser("list-archive", help="Архив встреч за окно дат (сеть, FR-9)")
+    p_arch.add_argument("--from", dest="from_date", required=True)
+    p_arch.add_argument("--to", dest="to_date", required=True)
+    p_arch.add_argument("--room-name", action="append", default=None)
+    p_arch.add_argument("--json", action="store_true")
+
+    p_chat = sub.add_parser("get-chat-messages", help="Сообщения чата встречи (сеть, FR-10)")
+    p_chat.add_argument("--recording-key", default=None)
+    p_chat.add_argument("--conference-key", default=None)
+    p_chat.add_argument("--channel", default=None)
+    p_chat.add_argument("--json", action="store_true")
+
+    p_cal = sub.add_parser("list-calendar", help="Календарь встреч (сеть, FR-18)")
+    p_cal.add_argument("--start", required=True, help="Начало окна (ISO 8601), включительно")
+    p_cal.add_argument("--end", required=True, help="Конец окна (ISO 8601), включительно")
+    p_cal.add_argument("--room-name", default=None)
+    p_cal.add_argument("--json", action="store_true")
+
+    p_room = sub.add_parser(
+        "get-room",
+        help="Детали комнаты (сеть, FR-17 — ПОБОЧНЫЙ ЭФФЕКТ: создаёт комнату, если имя новое)",
+    )
+    p_room.add_argument("room_name")
+    p_room.add_argument("--json", action="store_true")
+
+
+def _run(coro, formatter, *, json_flag: bool, **formatter_kwargs) -> int:
+    try:
+        data = asyncio.run(coro)
+    except Exception as exc:  # noqa: BLE001 - surface as CLI error, NFR-5 маскирует
+        print(f"Ошибка: {redact_secrets(str(exc))}", file=sys.stderr)
+        return 1
+    fmt = "raw" if json_flag else "markdown"
+    print(render_tool_output(data, fmt, formatter, **formatter_kwargs))
+    return 0
+
+
+async def _list_archive(args: argparse.Namespace) -> list[dict]:
+    async with KTalkClient.from_settings(Settings()) as client:
+        return await client.list_archive(
+            from_date=args.from_date, to_date=args.to_date, room_names=args.room_name
+        )
+
+
+def cmd_list_archive(_reg, args: argparse.Namespace) -> int:
+    return _run(_list_archive(args), format_archive_list, json_flag=args.json)
+
+
+async def _get_chat_messages(args: argparse.Namespace) -> list[dict]:
+    async with KTalkClient.from_settings(Settings()) as client:
+        return await client.get_chat_messages(
+            recording_key=args.recording_key,
+            conference_key=args.conference_key,
+            channel=args.channel,
+        )
+
+
+def cmd_get_chat_messages(_reg, args: argparse.Namespace) -> int:
+    return _run(_get_chat_messages(args), format_chat_messages, json_flag=args.json)
+
+
+async def _list_calendar(args: argparse.Namespace) -> dict:
+    async with KTalkClient.from_settings(Settings()) as client:
+        result = await get_calendar_window(
+            client, date.fromisoformat(args.start), date.fromisoformat(args.end),
+            room_name=args.room_name,
+        )
+    return {
+        "items": result.items,
+        "incomplete_segments": [
+            [s.isoformat(), e.isoformat()] for s, e in result.incomplete_segments
+        ],
+    }
+
+
+def cmd_list_calendar(_reg, args: argparse.Namespace) -> int:
+    return _run(_list_calendar(args), format_calendar, json_flag=args.json)
+
+
+async def _get_room(args: argparse.Namespace) -> dict:
+    async with KTalkClient.from_settings(Settings()) as client:
+        return await get_room(client, args.room_name)
+
+
+def cmd_get_room(_reg, args: argparse.Namespace) -> int:
+    return _run(_get_room(args), format_room, json_flag=args.json)

ktalk_cli/cli_sanction.py

@@ -0,0 +1,108 @@
+"""ADR-016 §3: `ktalk sanction status|grant|revoke` — выдача и отзыв мандата на запись.
+
+TTY-проверка живёт здесь, а не в `write_sanction.py`: модуль остаётся тестируемым,
+барьер — непроходимым из кода. Флага `--force`/`--yes` и переменной окружения,
+обходящей проверку, нет намеренно: обходной путь «для тестов» является обходным
+путём и в бою (ADR-014 §8).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from ktalk_cli import write_sanction
+from ktalk_cli.write_sanction import DEFAULT_HOURS, DEFAULT_OPERATIONS, OPERATIONS
+
+EXIT_OK = 0
+EXIT_BAD_ARGS = 2
+EXIT_INTERNAL = 20
+EXIT_NO_TTY = 43
+
+_CLI_TO_OPERATION = {operation.replace("_", "-"): operation for operation in OPERATIONS}
+
+
+def register_subparsers(sub) -> None:
+    parser = sub.add_parser("sanction", help="Санкция на запись в контур (ADR-016)")
+    actions = parser.add_subparsers(dest="sanction_action")
+
+    p_status = actions.add_parser("status", help="Состояние санкций")
+    p_status.add_argument("--json", action="store_true")
+
+    p_grant = actions.add_parser("grant", help="Выдать санкцию (только в терминале)")
+    p_grant.add_argument("operation", choices=sorted(_CLI_TO_OPERATION))
+    p_grant.add_argument("--hours", type=int, default=DEFAULT_HOURS)
+    p_grant.add_argument("--operations", type=int, default=DEFAULT_OPERATIONS)
+
+    p_revoke = actions.add_parser("revoke", help="Отозвать санкцию")
+    p_revoke.add_argument("operation", choices=[*sorted(_CLI_TO_OPERATION), "all"])
+
+
+def _state_json(state) -> dict:
+    return {
+        "status": state.status,
+        "active": state.active,
+        "expires_at": state.expires_at,
+        "remaining": state.remaining,
+    }
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    states = {operation: write_sanction.read_state(operation) for operation in OPERATIONS}
+    if args.json:
+        print(json.dumps({key: _state_json(state) for key, state in states.items()}))
+    else:
+        for operation, state in states.items():
+            suffix = (
+                f", до {state.expires_at}, осталось операций: {state.remaining}"
+                if state.expires_at
+                else ""
+            )
+            print(f"{operation}: {state.status}{suffix}")
+        print(f"Файл: {write_sanction.sanction_path()}")
+    return EXIT_OK
+
+
+def _cmd_grant(args: argparse.Namespace) -> int:
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        print(
+            "Санкция на запись выдаётся только в интерактивном терминале. "
+            f"Запустите вручную: ktalk sanction grant {args.operation}",
+            file=sys.stderr,
+        )
+        return EXIT_NO_TTY
+
+    operation = _CLI_TO_OPERATION[args.operation]
+    try:
+        state = write_sanction.grant(
+            operation, hours=args.hours, operations=args.operations
+        )
+    except ValueError as exc:
+        print(f"Ошибка: {exc}", file=sys.stderr)
+        return EXIT_INTERNAL
+
+    print(
+        f"Санкция «{args.operation}» выдана до {state.expires_at} "
+        f"на {state.remaining} операц(ий).\n"
+        f"Отзыв: ktalk sanction revoke {args.operation}\n"
+        f"Файл: {write_sanction.sanction_path()}"
+    )
+    return EXIT_OK
+
+
+def _cmd_revoke(args: argparse.Namespace) -> int:
+    targets = OPERATIONS if args.operation == "all" else (_CLI_TO_OPERATION[args.operation],)
+    for operation in targets:
+        write_sanction.revoke(operation)
+        print(f"Санкция «{operation.replace('_', '-')}» отозвана.")
+    return EXIT_OK
+
+
+def cmd_sanction(_reg, args: argparse.Namespace) -> int:
+    action = getattr(args, "sanction_action", None)
+    handler = {"status": _cmd_status, "grant": _cmd_grant, "revoke": _cmd_revoke}.get(action)
+    if handler is None:
+        print("Укажите действие: sanction status | grant | revoke", file=sys.stderr)
+        return EXIT_BAD_ARGS
+    return handler(args)