ktalk-cli 1.0.0__py3-none-any.whl

ktalk_cli/config.py

@@ -0,0 +1,152 @@
+import os
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+if TYPE_CHECKING:
+    from ktalk_cli.host_config import HostConfig
+
+
+class AuthMode(str, Enum):
+    """Активный механизм авторизации клиента (ADR-003)."""
+
+    SESSION = "session"
+    API_KEY = "api_key"
+
+
+class KTalkConfigError(Exception):
+    """Ни KTALK_PERSONAL_API_KEY, ни KTALK_SESSION_TOKEN не заданы."""
+
+
+def resolve_db_path(
+    cli_db: str | None = None, host_config: "HostConfig | None" = None
+) -> Path:
+    """Resolve the registry DB path (ADR-013 §3, расширено волной 3):
+
+    `--db` > `KTALK_REGISTRY_DB` > `host_config.registry.db_path` (SA-003,
+    discovery выполняется вызывающей стороной — `resolve_db_path` только
+    использует уже готовый `HostConfig`) > машинный дефолт централизованного
+    хранилища (`store.resolve_store_root`, FR-22).
+
+    Старый относительный дефолт `95_TRANSCRIPTS/.registry.db` (ADR-002) заменён
+    машинным дефолтом вне cwd (ADR-013) — единственный оставшийся источник
+    относительного пути в этой функции теперь `host_config`, если проект-хозяин
+    явно объявляет относительный `registry.db_path`.
+
+    Code review (epic-capability-pairing, Р4): `warn_if_sync_dir` (NFR-14 AC-2)
+    обязана применяться к итоговому пути независимо от источника (ADR-013-spec
+    §«Поток данных» п.4) — до этой правки вызывалась только в ветке машинного
+    дефолта; `--db`/`KTALK_REGISTRY_DB`/конфиг хозяина возвращали путь раньше.
+    """
+    from ktalk_cli.store import resolve_store_root, warn_if_sync_dir
+
+    if cli_db:
+        path = Path(cli_db)
+        warn_if_sync_dir(path)
+        return path
+    env = os.environ.get("KTALK_REGISTRY_DB")
+    if env:
+        path = Path(env)
+        warn_if_sync_dir(path)
+        return path
+    if host_config is not None:
+        configured = host_config.registry.get("db_path")
+        if configured:
+            path = Path(configured)
+            warn_if_sync_dir(path)
+            return path
+
+    path = resolve_store_root() / "registry.db"
+    warn_if_sync_dir(path)
+    return path
+
+
+class Settings(BaseSettings):
+    """KTalk MCP server configuration.
+
+    Environment variables:
+        KTALK_BASE_URL: KTalk instance URL (default: https://your-domain.ktalk.ru)
+        KTALK_SESSION_TOKEN: Session token from browser cookies
+        KTALK_PERSONAL_API_KEY: Персональный API-ключ (ADR-003) — приоритетнее сессии
+
+    Оба секретных поля опциональны на уровне модели (ADR-003): конструирование
+    `Settings()` никогда не падает само по себе. Приоритет режима (ключ -> сессия ->
+    явная ошибка) вычисляется лениво в `.auth_mode` — единственной точке, где
+    отсутствие ОБЕИХ переменных становится `KTalkConfigError`.
+
+    NFR-5 / security review (SEC-001): `ktalk_session_token`/`ktalk_personal_api_key`
+    объявлены `Field(repr=False)` — pydantic по умолчанию печатает значения ВСЕХ полей
+    в `repr(settings)`/`str(settings)` (в отличие от `AuthContext`, который уже маскирует
+    себя явно), а это ровно тот текст, что мог бы случайно попасть в отладочный
+    `print`/`logger.debug(settings)` или в текст будущего `ValidationError`.
+    """
+
+    ktalk_base_url: str = "https://your-domain.ktalk.ru"
+    ktalk_session_token: str | None = Field(default=None, repr=False)
+    ktalk_personal_api_key: str | None = Field(default=None, repr=False)
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    @model_validator(mode="after")
+    def _fall_back_to_token_file(self) -> "Settings":
+        """Третий источник сессии — файл `~/.config/ktalk-mcp/token` (token_file.py).
+
+        Подставляется здесь, а не в `.auth_mode`, чтобы у файла и у переменной
+        окружения была ровно одна точка входа в модель: всё остальное (приоритет
+        ключа, `auth_credential`, барьер маскирования `redact_secrets`) продолжает
+        читать одно поле и о существовании файла не знает.
+
+        Порядок источников: `KTALK_PERSONAL_API_KEY` > `KTALK_SESSION_TOKEN` > файл.
+        Файл читается только когда пусты ОБЕ переменные — заданное окружение
+        сильнее лежащего на диске, иначе протухший файл молча перебивал бы токен,
+        который оператор передал явно.
+        """
+        if self.ktalk_personal_api_key or self.ktalk_session_token:
+            return self
+        from ktalk_cli.token_file import read_token
+
+        token = read_token()
+        if token:
+            object.__setattr__(self, "ktalk_session_token", token)
+        return self
+
+    @property
+    def auth_mode(self) -> AuthMode:
+        if self.ktalk_personal_api_key:
+            return AuthMode.API_KEY
+        if self.ktalk_session_token:
+            return AuthMode.SESSION
+        raise KTalkConfigError(
+            "Не задана ни KTALK_PERSONAL_API_KEY, ни KTALK_SESSION_TOKEN, "
+            "и файла токена нет. Задайте переменную или выполните "
+            "`ktalk token set -` (см. README)."
+        )
+
+    @property
+    def auth_credential(self) -> str:
+        # .auth_mode уже проверил, что хотя бы одно поле непустое.
+        return self.ktalk_personal_api_key or self.ktalk_session_token or ""
+
+
+def redact_secrets(text: str) -> str:
+    """Барьер маскирования (NFR-5, ADR-003 «SecretRedactor», ранее спроектирован, но не
+    вызывался ниоткуда — security review SEC-001).
+
+    Ни `KTalkError`, ни `httpx`-обёртки этого проекта сегодня не строят текст ошибки из
+    `request.url`/`request.headers`/`repr(request)` (проверено ревью) — секрет не должен
+    появиться в тексте исключения. Это тем не менее последний рубеж на границе CLI: если
+    секрет всё же попадёт в текст произвольного, не-`KTalkError`-исключения (например, из
+    сторонней зависимости, которая не следует той же дисциплине), значение маскируется
+    здесь перед печатью, а не полагается только на дисциплину каждого источника ошибки.
+    """
+    try:
+        settings = Settings()
+    except Exception:  # noqa: BLE001 - барьер не должен сам стать новым источником отказа
+        return text
+    for value in (settings.ktalk_personal_api_key, settings.ktalk_session_token):
+        if value:
+            text = text.replace(value, "***REDACTED***")
+    return text

ktalk_cli/confirmation.py

@@ -0,0 +1,129 @@
+"""FR-13 §6.2: хранилище подтверждений — TTL, single-use, привязка к хешу тела
+(ADR-005-spec «Форма подтверждения»/«Сценарии отказа»).
+
+ADR-016 §2: хранилище переехало из памяти в файл `$XDG_STATE_HOME/ktalk`. Вывод
+ADR-015 «`confirmation_id` не переживает границу процессов» был следствием
+хранилища в памяти, а не свойством задачи, и снят вместе с причиной: агент теперь
+выполняет и предпросмотр, и подтверждение, и именно id связывает предъявленное
+оператору тело с фактической записью.
+
+TTL, одноразовость и неразличимость причин отказа (`match` возвращает один `False`)
+не пересматриваются. Битый или нечитаемый файл читается как пустое хранилище —
+fail-closed: все подтверждения недействительны, а не «проверку пропустить».
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+# Дизайн-выбор, не измеренная величина (тот же класс решения, что concurrency=5 в
+# enrichment.py) — обоснование в rooms-calendar-spec §6.2.
+CONFIRMATION_TTL = timedelta(minutes=10)
+
+
+@dataclass(frozen=True)
+class ConfirmationRecord:
+    body_hash: str
+    expires_at: datetime  # UTC-aware
+
+
+def confirmation_store_path() -> Path:
+    """Состояние, а не конфигурация -> `$XDG_STATE_HOME`, не `$XDG_CONFIG_HOME`;
+    и не рядом с транскриптами в `$XDG_DATA_HOME` (ADR-013 — данные пользователя,
+    переживающие переустановку; подтверждение живёт десять минут)."""
+    xdg_state_home = os.environ.get("XDG_STATE_HOME") or None
+    root = Path(xdg_state_home) if xdg_state_home else Path.home() / ".local" / "state"
+    return root / "ktalk" / "pending-confirmations.json"
+
+
+class ConfirmationStore:
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], datetime] = lambda: datetime.now(timezone.utc),
+        path: Path | None = None,
+    ) -> None:
+        self._clock = clock
+        self._path = path
+
+    @property
+    def path(self) -> Path:
+        return self._path if self._path is not None else confirmation_store_path()
+
+    def _load(self) -> dict[str, ConfirmationRecord]:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        records: dict[str, ConfirmationRecord] = {}
+        if not isinstance(raw, dict):
+            return {}
+        for confirmation_id, record in raw.items():
+            try:
+                expires_at = datetime.fromisoformat(record["expires_at"])
+                records[confirmation_id] = ConfirmationRecord(
+                    body_hash=record["body_hash"], expires_at=expires_at
+                )
+            except (TypeError, KeyError, ValueError):
+                continue
+        return records
+
+    def _save(self, records: dict[str, ConfirmationRecord]) -> None:
+        path = self.path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        os.chmod(path.parent, 0o700)
+        payload = {
+            confirmation_id: {
+                "body_hash": record.body_hash,
+                "expires_at": record.expires_at.isoformat(),
+            }
+            for confirmation_id, record in records.items()
+        }
+        tmp = path.with_name(f".{path.name}.tmp")
+        tmp.write_text(json.dumps(payload), encoding="utf-8")
+        os.chmod(tmp, 0o600)
+        tmp.replace(path)
+
+    def issue(self, body_hash: str) -> str:
+        """Непредсказуемый одноразовый идентификатор, не производный от `body_hash`
+        — иначе агент вычислил бы его локально, минуя факт вызова предпросмотра.
+        Попутно вычищает истёкшие записи: файл не растёт бесконечно, и уборка не
+        требует отдельной команды."""
+        # Префикс `c` — не украшение: `token_urlsafe` может начаться с `-`, и такой
+        # id argparse принимает за флаг (`--confirmation-id -x8Q…` -> «expected one
+        # argument»). В памяти это было безразлично, на границе командной строки —
+        # плавающий отказ примерно в каждом двадцатом вызове (DEV-012).
+        confirmation_id = f"c{secrets.token_urlsafe(24)}"
+        now = self._clock()
+        records = {
+            key: record for key, record in self._load().items() if now < record.expires_at
+        }
+        records[confirmation_id] = ConfirmationRecord(
+            body_hash=body_hash, expires_at=now + CONFIRMATION_TTL
+        )
+        self._save(records)
+        return confirmation_id
+
+    def match(self, confirmation_id: str, body_hash: str) -> bool:
+        """id неизвестен/потреблён/TTL истёк/хеш не совпал -> одно и то же `False`
+        (не различаем причины наружу — ничего из этого не должно ускользать в
+        подсказку "как обойти")."""
+        record = self._load().get(confirmation_id)
+        if record is None:
+            return False
+        if self._clock() >= record.expires_at:
+            return False
+        return record.body_hash == body_hash
+
+    def consume(self, confirmation_id: str) -> None:
+        """Вызывается ДО сетевой попытки — повтор после сбоя требует нового
+        предпросмотра и нового подтверждения, не автоматического retry."""
+        records = self._load()
+        if records.pop(confirmation_id, None) is not None:
+            self._save(records)

ktalk_cli/contacts.py

@@ -0,0 +1,45 @@
+"""ADR-010: резолюция участника встречи через справочник контактов
+(`GET /api/contacts`) — маппер + сетевой вызов вне `client.py` (гейт C13).
+
+Вынесено свободной функцией по тому же приёму, что `rooms.get_room`. Читающая
+операция, не мутирует состояние — не оборачивается корреляционной диагностикой
+ADR-004 (тот же класс, что `get_room`).
+"""
+
+from __future__ import annotations
+
+from ktalk_cli.auth import _display_name
+from ktalk_cli.client import KTalkClient
+
+_TOP = 25
+
+
+def _map_candidate(raw: dict) -> dict:
+    return {
+        "key": raw.get("key"),
+        "name": _display_name(raw),
+        "post": raw.get("post"),
+    }
+
+
+async def search_contacts(client: KTalkClient, query: str) -> list[dict]:
+    """Один GET `/api/contacts` -> список кандидатов `{key, name, post}`.
+
+    `top=25`, `fillInMeetingStatus=false`, `includeKiosks=true` — фиксированные
+    константы компоновщика запроса (ADR-010-spec §«Интеграционные точки»), не
+    параметры вызывающего в этой волне. Автовыбора нет: 0/1/>1 совпадений —
+    решение оператора остаётся снаружи (см. `formatters.format_search_contacts`).
+    """
+    profile = client._profile_for("search_contacts")  # noqa: SLF001 - fail-closed до сети (api-key)
+    response = await client._client.get(  # noqa: SLF001
+        profile.path_template,
+        params={
+            "query": query,
+            "top": _TOP,
+            "fillInMeetingStatus": "false",
+            "includeKiosks": "true",
+        },
+    )
+    client._classify(response, profile.required_scope)  # noqa: SLF001
+    raw = response.json()
+    return [_map_candidate(c) for c in raw.get("contacts") or []]

ktalk_cli/contour_diagnostics.py

@@ -0,0 +1,107 @@
+"""Корреляционная диагностика недокументированного контура (ADR-004).
+
+Единственный переиспользуемый компонент FR-17/FR-18 (rooms.py, calendar_reader.py):
+отказ на недокументированном пути сам по себе неотличим от обычного auth/сетевого
+сбоя — модуль запускает контрольный вызов (`list_recordings(top=1)`, уже подтверждён
+рабочим в обоих режимах) и решает, где локализована проблема.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from ktalk_cli.client import (
+    KTalkAuthError,
+    KTalkClient,
+    KTalkError,
+    KTalkScopeError,
+    KTalkWriteAuthMismatchError,
+)
+
+TRANSIENT_ERRORS = (KTalkError, httpx.HTTPError)
+
+
+class ContourDriftError(KTalkError):
+    """Контрольная операция в порядке, но недокументированный путь отказал —
+    сбой локализован там, не в правах/сети (ADR-004 «Механизм детекции»)."""
+
+    def __init__(self, operation: str, detail: str) -> None:
+        self.operation = operation
+        self.detail = detail
+        super().__init__(
+            f"Недокументированная операция «{operation}» ведёт себя не так, как "
+            f"ожидалось (контроль авторизации прошёл): {detail}"
+        )
+
+
+def _status_hint(error: Exception) -> str:
+    """Код ответа для текста сообщения (ADR-008 §2). `_with_status` (client.py)
+    прикрепляет `status_code` на исключении при классификации — используется,
+    если есть; иначе — общая формулировка без числа (не должно происходить для
+    401/403, оставлено как защита от рассинхронизации)."""
+    status = getattr(error, "status_code", None)
+    return f"HTTP {status}" if status is not None else "ошибку авторизации"
+
+
+def _describe_control_failure(control_error: Exception) -> str:
+    """DEV-008: класс/HTTP-код/текст контрольного вызова — тот же формат, что
+    `_status_hint`, но не глотает исключение целиком. Нужен, когда контроль ТОЖЕ
+    падает: раньше его исход терялся в `raise error from None`, и человек не мог
+    отличить «контроль упал» от «диагностика не отработала»."""
+    status = getattr(control_error, "status_code", None)
+    status_part = f"HTTP {status}" if status is not None else "без HTTP-кода"
+    return f"{type(control_error).__name__} ({status_part}): {control_error}"
+
+
+async def diagnose_undocumented_failure(
+    client: KTalkClient, operation: str, error: Exception
+) -> None:
+    """Всегда завершается исключением: либо перевыбрасывает `error` (контроль тоже
+    провалился — не дрейф контура), либо поднимает `KTalkWriteAuthMismatchError`
+    (ADR-008: исходная ошибка — 401/403, не scope-специфичная, контроль в порядке —
+    credential подтверждён рабочим независимой проверкой), либо `ContourDriftError`
+    (прочие классы сбоя — контроль в порядке, сбой локализован в недокументированном
+    пути)."""
+    try:
+        await client.list_recordings(top=1)
+    except TRANSIENT_ERRORS as control_error:
+        # DEV-008: контроль тоже упал — это не "диагностика не отработала", а
+        # самостоятельный факт, который должен дойти до человека вместе с
+        # исходной ошибкой, не молча (`except TRANSIENT_ERRORS: raise error from
+        # None` раньше терял его целиком).
+        error.control_probe = (
+            "Контрольный вызов list_recordings(top=1) тоже упал: "
+            f"{_describe_control_failure(control_error)}."
+        )
+        raise error from None
+    if isinstance(error, KTalkAuthError) and not isinstance(error, KTalkScopeError):
+        new_exc = KTalkWriteAuthMismatchError(
+            f"Операция «{operation}» вернула {_status_hint(error)}, хотя тот же credential "
+            "подтверждён рабочим независимой проверкой (list_recordings) в ту же секунду. "
+            "Обновлять токен/ключ не нужно — причина в том, как именно эта операция "
+            "принимает credential (см. ADR-008), не в его валидности."
+        )
+        _carry(error, new_exc)
+        raise new_exc from error
+    new_drift = ContourDriftError(operation, str(error))
+    _carry(error, new_drift)
+    raise new_drift from error
+
+
+def _carry(error: Exception, derived: Exception) -> None:
+    """DEV-012 (ADR-016 §5): вместе с телом ответа переносится и `status_code`.
+    Без него журнал операций не отличал «сервер отказал» от «ответа не было» на той
+    ветке, где контроль прошёл, — а именно этот класс исходов и разбирают постфактум."""
+    derived.response_body = getattr(error, "response_body", None)
+    status_code = getattr(error, "status_code", None)
+    if status_code is not None:
+        derived.status_code = status_code
+
+
+def require_contract_field(payload: dict, field: str, operation: str) -> None:
+    """ContourDriftError вместо тихого KeyError/None при отсутствии поля-якоря
+    контракта на коде 200 — без корреляции (доступ уже подтверждён кодом 200)."""
+    if field not in payload:
+        raise ContourDriftError(
+            operation, f"поле-якорь контракта «{field}» отсутствует в ответе 200."
+        )

ktalk_cli/download.py

@@ -0,0 +1,109 @@
+"""Потоковая запись видеофайла записи на диск (FR-7).
+
+Session-режим — ссылка уже готова в `qualities[].fileUrl` деталей записи.
+Api-key-режим — отдельный путь с именем качества в шаблоне (`RES-001` п.5), список
+доступных качеств под ключом взять неоткуда (открытый вопрос SA) — запрошенное
+качество используется как есть, без валидации по списку.
+
+Зонд Ф-7: имя качества расходится между режимами (`900p` без пробела в session,
+`900 p` с пробелом рекомендует спека api-key) — наивная сборка URL с пробелом
+ломается (`InvalidURL`). `build_download_url` нормализует и квотирует.
+
+Политика записи на диск — базовый безопасный минимум (SA сознательно оставил её
+открытой, полное ревью — DevSecOps): пишем только по явно переданному пути, не
+угадываем и не создаём файлы в неожиданных местах, отказываем при попытке
+перезаписать существующий файл без явного `overwrite=True`.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from urllib.parse import quote
+
+from ktalk_cli.config import AuthMode
+
+DEFAULT_QUALITY = "900p"
+
+
+class QualityNotFoundError(Exception):
+    """Запрошенное качество недоступно для этой записи (FR-7 AC-3)."""
+
+
+def _normalize_quality(quality: str) -> str:
+    """`900p` и `900 p` -> одна и та же каноническая форма без пробела."""
+    return quality.replace(" ", "").lower()
+
+
+def build_download_url(recording_key: str, quality: str) -> str:
+    """Api-key-путь скачивания, URL-квотированный (FR-7 AC-2, зонд Ф-7)."""
+    normalized = _normalize_quality(quality)
+    key = quote(str(recording_key), safe="")
+    q = quote(normalized, safe="")
+    return f"/api/Recordings/{key}/file/{q}"
+
+
+def _resolve_session_quality(qualities: list[dict], quality: str | None) -> tuple[str, str]:
+    if not qualities:
+        raise QualityNotFoundError("У записи нет доступных качеств скачивания.")
+    by_normalized = {_normalize_quality(q.get("name", "")): q for q in qualities}
+    wanted = _normalize_quality(quality) if quality else next(iter(by_normalized))
+    match = by_normalized.get(wanted)
+    if match is None:
+        available = ", ".join(q.get("name", "?") for q in qualities)
+        raise QualityNotFoundError(
+            f"Качество «{quality}» недоступно для этой записи. Доступные: {available}."
+        )
+    return match.get("name", wanted), match["fileUrl"]
+
+
+async def download_recording_file(
+    client,
+    recording_key: str,
+    target_path: str,
+    quality: str | None = None,
+    *,
+    overwrite: bool = False,
+) -> dict:
+    """Скачивает файл записи потоково, без буферизации целиком в памяти (FR-7 AC-4)."""
+    if client.auth_mode is AuthMode.API_KEY:
+        resolved_quality = quality or DEFAULT_QUALITY
+        url = build_download_url(recording_key, resolved_quality)
+        scope = "application.recording.read"
+    else:
+        detail = await client.get_recording(recording_key)
+        resolved_quality, url = _resolve_session_quality(detail.get("qualities") or [], quality)
+        scope = None
+
+    target = Path(target_path)
+    if target.exists() and not overwrite:
+        # Быстрый отказ до сетевого вызова — сохраняет прежнее поведение/сообщение.
+        raise FileExistsError(
+            f"Файл уже существует: {target}. Укажите overwrite=True для перезаписи."
+        )
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    total = 0
+    async with client.stream("GET", url) as response:
+        client.check_response(response, scope)
+        # Security review SEC-001: `target.exists()` выше следует за симлинками и
+        # возвращает False для «оборванного» симлинка (указывающего на
+        # несуществующий путь) — наивный `target.open("wb")` в этом случае писал бы
+        # СКВОЗЬ симлинк в произвольное место, куда указывает ссылка. Между
+        # проверкой и записью есть и обычное TOCTOU-окно (сетевой вызов между ними).
+        # `os.O_EXCL` с `os.O_CREAT` атомарно отказывает и на гонке, и на висящем
+        # симлинке (POSIX). При `overwrite=True` поведение не меняется — перезапись
+        # была осознанно запрошена вызывающим.
+        flags = os.O_WRONLY | os.O_CREAT | (0 if overwrite else os.O_EXCL)
+        try:
+            fd = os.open(target, flags, 0o644)
+        except FileExistsError as exc:
+            raise FileExistsError(
+                f"Файл уже существует: {target}. Укажите overwrite=True для перезаписи."
+            ) from exc
+        with os.fdopen(fd, "wb") as fh:
+            async for chunk in response.aiter_bytes():
+                fh.write(chunk)
+                total += len(chunk)
+
+    return {"path": str(target), "bytes": total, "quality": resolved_quality}