ktalk-cli 1.0.0__py3-none-any.whl

ktalk_cli/store.py

@@ -0,0 +1,88 @@
+"""Централизованное машинное хранилище (ADR-013): корень, права, детекция
+облачной синхронизации.
+
+Companion-спека: `content/40-architecture/ADR-013-central-transcript-store-spec.md`.
+Отдельный модуль от `registry.py` (грандфазер заморожен на 562 строках).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_STORE_DIR_NAME = "ktalk"
+
+# NFR-14: маркеры известных каталогов облачной синхронизации. Сегментация по
+# границе каталога, не substring — `MyDropboxBackup/` не должен ложно
+# сработать на `Dropbox` (ADR-013-spec, boundary).
+_SYNC_MULTI_SEGMENT_MARKERS: tuple[tuple[str, str], ...] = (
+    ("Library", "Mobile Documents"),
+    ("Library", "CloudStorage"),
+)
+_SYNC_SINGLE_SEGMENT_MARKERS: tuple[str, ...] = (
+    "Dropbox",
+    "Google Drive",
+    "OneDrive",
+    "Nextcloud",
+    "ownCloud",
+)
+
+
+def resolve_store_root() -> Path:
+    """Резолвит и создаёт корень централизованного хранилища (ADR-013 §1).
+
+    `${XDG_DATA_HOME:-$HOME/.local/share}/ktalk`. `$XDG_DATA_HOME=""` (пустая
+    строка) трактуется как «не задано», не как путь `""` (boundary case).
+
+    Права `0700` на каталог и, transitively, `0600` на файлы, создаваемые этим
+    процессом впоследствии (в т.ч. `registry.db` через `sqlite3.connect`) —
+    обеспечивается процессным `umask`, применённым здесь один раз, а не
+    ретроактивным `chmod` (NFR-15: «без окна между созданием и ограничением
+    прав»). Побочный эффект осознанный: с момента первого разрешения корня
+    хранилища процесс создаёт любые файлы владелец-only до конца своего цикла
+    жизни — это соответствует всей раскладке хранилища (`registry.db`, `-wal`,
+    `-shm`, `transcripts/`, `eval/reports/`), не только одному файлу.
+    """
+    xdg_data_home = os.environ.get("XDG_DATA_HOME") or None
+    if xdg_data_home:
+        base = Path(xdg_data_home)
+    else:
+        home = os.environ.get("HOME") or str(Path.home())
+        base = Path(home) / ".local" / "share"
+    root = base / _STORE_DIR_NAME
+    os.umask(0o077)
+    root.mkdir(parents=True, exist_ok=True)
+    # MAJ-03 (security review SEC-003): `mkdir(exist_ok=True)` не чинит режим уже
+    # существующего каталога — безусловный `chmod`, не только при первом создании,
+    # закрывает случай «каталог остался с ослабленными правами от более ранней
+    # версии/ручного создания/восстановления из бэкапа».
+    os.chmod(root, 0o700)
+    return root
+
+
+def detect_sync_dir(path: str | Path) -> tuple[bool, str]:
+    """Эвристика NFR-14: путь внутри известного каталога облачной синхронизации.
+
+    Не платформенный API (нет надёжного), а сегментированная проверка частей
+    пути — не гарантия, известное ограничение (ADR-013, Consequences).
+    """
+    parts = [p.lower() for p in Path(path).parts]
+    for seg1, seg2 in _SYNC_MULTI_SEGMENT_MARKERS:
+        s1, s2 = seg1.lower(), seg2.lower()
+        for i in range(len(parts) - 1):
+            if parts[i] == s1 and parts[i + 1] == s2:
+                return True, f"путь внутри каталога облачной синхронизации ({seg1}/{seg2})"
+    for marker in _SYNC_SINGLE_SEGMENT_MARKERS:
+        if marker.lower() in parts:
+            return True, f"путь внутри каталога облачной синхронизации ({marker})"
+    return False, "путь вне известных каталогов облачной синхронизации"
+
+
+def warn_if_sync_dir(path: str | Path) -> bool:
+    """NFR-14 AC-2: путь внутри каталога синхронизации -> предупреждение в
+    stderr, работа продолжается (не блокировка)."""
+    is_sync, reason = detect_sync_dir(path)
+    if is_sync:
+        print(f"Предупреждение: {reason}: {path}", file=sys.stderr)
+    return is_sync

ktalk_cli/store_migration.py

@@ -0,0 +1,89 @@
+"""Миграция реестра в централизованное хранилище — явный обратимый шаг (NFR-12).
+
+Companion-спека: `content/40-architecture/ADR-013-central-transcript-store-spec.md`,
+«Контракт команды миграции». Отдельно от `ktalk migrate <vault>` (`registry.py`,
+`migrate_from_vault`) — та импортирует markdown-архивы (ADR-002), эта копирует
+существующий SQLite-реестр на новый путь. Read-only использование `registry.py`
+(построчный дамп через `sqlite3.iterdump`), не расширяет его.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sqlite3
+from datetime import date
+from pathlib import Path
+
+
+class MigrationVerificationError(Exception):
+    """Построчная сверка дампа источник<->копия не совпала — миграция отменена,
+    источник не тронут, целевой файл удалён (не остаётся частичной копией)."""
+
+
+class MigrationTargetExistsError(Exception):
+    """Целевой файл уже существует — повторный вызов не перезаписывает данные,
+    добавленные в централизованное хранилище другим проектом после первой
+    миграции."""
+
+
+def _dump_lines(db_path: Path) -> list[str]:
+    conn = sqlite3.connect(str(db_path))
+    try:
+        return list(conn.iterdump())
+    finally:
+        conn.close()
+
+
+def _dumps_match(source: Path, target: Path) -> bool:
+    return _dump_lines(source) == _dump_lines(target)
+
+
+def migrate_to_central_store(source: str | Path, target: str | Path) -> Path:
+    """Copy -> построчная сверка дампа -> backup-переименование источника.
+
+    Источник не удаляется — переименовывается в `<имя>.pre-migration-<дата>`
+    только после совпадения сверки. Не запускается неявно (NFR-12 AC-1) — вызов
+    только явный, из отдельной CLI-команды/скрипта, не из `Registry.__init__`.
+    """
+    source = Path(source)
+    target = Path(target)
+
+    # BLOCK-01/MAJ-03 (security review SEC-003): права цели — NFR-15 (0700/0600)
+    # независимо от прав источника и от ambient umask, безусловно, не только при
+    # первом создании каталога — `mkdir(exist_ok=True)` не чинит уже существующий
+    # каталог со слабыми правами.
+    target.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(target.parent, 0o700)
+
+    # MIN-01: check-then-act между `target.exists()` и созданием файла закрыт —
+    # `O_EXCL` делает проверку-и-создание одной атомарной операцией ОС, не двумя
+    # раздельными шагами. Явный `mode=0o600` при создании — права заданы с
+    # рождения файла, не пост-хок `chmod`/`copy2` (который перенёс бы биты
+    # источника поверх).
+    try:
+        fd = os.open(str(target), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError as exc:
+        raise MigrationTargetExistsError(
+            f"Целевой файл уже существует: {target} — повторная миграция не "
+            "перезаписывает данные, добавленные после предыдущей миграции"
+        ) from exc
+
+    try:
+        with os.fdopen(fd, "wb") as dst_f, open(source, "rb") as src_f:
+            shutil.copyfileobj(src_f, dst_f)
+        os.chmod(target, 0o600)  # copyfileobj не переносит metadata — явный chmod всё равно
+    except BaseException:
+        target.unlink(missing_ok=True)
+        raise
+
+    if not _dumps_match(source, target):
+        target.unlink(missing_ok=True)
+        raise MigrationVerificationError(
+            f"Сверка дампа не совпала: {source} != {target}; источник не тронут, "
+            "целевой файл удалён"
+        )
+
+    backup = source.with_name(f"{source.name}.pre-migration-{date.today().isoformat()}")
+    source.rename(backup)
+    return target

ktalk_cli/token_file.py

@@ -0,0 +1,101 @@
+"""Файл session-токена — третий источник авторизации после `KTALK_PERSONAL_API_KEY`
+и `KTALK_SESSION_TOKEN` (ADR-003 расширен: приоритет ключ -> env-сессия -> файл).
+
+Зачем файл вообще нужен. Session-токен протухает и обновляется руками; окружение
+для этого — плохой носитель: экспорт в `.zshrc` не доходит до MCP-сервера,
+запущенного Claude Code, а `.env` привязан к рабочей директории. Файл лежит в
+одном месте, переживает перезапуск обоих процессов и обновляется одной командой.
+
+Каталог `ktalk-mcp/`, не `ktalk/`: в `ktalk/` живёт санкция на запись (ADR-016),
+у неё другой жизненный цикл и другой владелец решения.
+
+Права шире `0600` читаются как «файла нет» — тот же fail-closed барьер, что у
+санкции записи (SEC-006). Это защита не от владельца учётной записи, а от другого
+пользователя машины, которому файл стал доступен.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+from pathlib import Path
+
+# Наблюдаемый формат session-токена — одно слово из букв и цифр (боевой токен
+# 2026-08-21: 20 символов; прецедент mainpart проверяет `^[A-Za-z0-9]{16,40}$`,
+# см. research/mainpart-ktalk-mcp.md §«Авторизация», п.2). Верхняя граница поднята
+# до 64 с запасом: узкая граница отвергла бы валидный токен, широкая — пропускает
+# ровно то, что и должна отвергать (пути, JSON, куски команд из устаревшего буфера).
+_TOKEN_RE = re.compile(r"^[A-Za-z0-9]{16,64}$")
+
+
+def token_path() -> Path:
+    """`KTALK_TOKEN_FILE` (полный путь) > `$XDG_CONFIG_HOME/ktalk-mcp/token` >
+    `~/.config/ktalk-mcp/token`."""
+    override = os.environ.get("KTALK_TOKEN_FILE")
+    if override:
+        return Path(override)
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME") or None
+    root = Path(xdg_config_home) if xdg_config_home else Path.home() / ".config"
+    return root / "ktalk-mcp" / "token"
+
+
+def file_mode() -> str | None:
+    """Права файла как `0600` — для диагностики. `None`, если файла нет."""
+    try:
+        return format(stat.S_IMODE(token_path().stat().st_mode), "04o")
+    except OSError:
+        return None
+
+
+def read_token() -> str | None:
+    """Значение токена или `None` — если файла нет, он нечитаем, пуст или его
+    права шире `0600`. Ни одна из этих причин не является ошибкой: вызывающая
+    сторона просто переходит к следующему источнику (или к отказу конфигурации)."""
+    path = token_path()
+    try:
+        if stat.S_IMODE(path.stat().st_mode) & 0o077:
+            return None
+        raw = path.read_text(encoding="utf-8")
+    except (OSError, ValueError, UnicodeDecodeError):
+        return None
+    token = raw.strip()
+    return token or None
+
+
+def write_token(value: str) -> Path:
+    """Пишет токен с правами `0600` в каталоге `0700` и возвращает путь.
+
+    `os.replace` поверх временного файла: параллельно читающий процесс видит либо
+    старый токен целиком, либо новый целиком, но никогда полупустой файл. Права
+    выставляются до переименования — окна, в котором секрет лежит доступным всем,
+    не существует.
+    """
+    token = value.strip()
+    if not token:
+        raise ValueError("Пустой токен: записывать нечего.")
+    if not _TOKEN_RE.match(token):
+        # Значение в текст ошибки не попадает: буфер обмена мог содержать чужой
+        # секрет. Названы только длина и правило — этого хватает, чтобы понять,
+        # что скопировано не то (находка живой проверки 2026-08-21).
+        raise ValueError(
+            f"Значение длиной {len(token)} символ(ов) не похоже на токен: "
+            "ожидается одно слово из букв и цифр, 16-64 символа. "
+            "Проверьте, что в буфере результат `copy(JSON.parse(localStorage.session).data.token)`."
+        )
+
+    path = token_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path.parent.chmod(0o700)
+
+    tmp = path.with_name(path.name + ".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(token)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+    os.replace(tmp, path)
+    path.chmod(0o600)
+    return path

ktalk_cli/write_journal.py

@@ -0,0 +1,94 @@
+"""ADR-016 §4/§5: журнал пишущих операций — прослеживаемость каждой попытки.
+
+Две строки на операцию, не одна: `attempt` без парной `outcome` — машинный след
+«процесс не дожил до ответа», отличимый от «ответа не было» (`result: unknown`).
+Именно этот класс исходов стоил волне 0.6.0 четырёх разборов вручную.
+
+Отказ записи `attempt` — fail-closed: сетевого вызова не будет. Иначе
+прослеживаемость исчезает ровно тогда, когда она нужна.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ktalk_cli.config import redact_secrets
+
+
+class JournalUnavailableError(OSError):
+    """Журнал недоступен для записи — пишущая операция не выполняется."""
+
+
+def journal_path() -> Path:
+    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" / "write-ops.jsonl"
+
+
+def _append(record: dict) -> None:
+    path = journal_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        os.chmod(path.parent, 0o700)
+        existed = path.exists()
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+        if not existed:
+            os.chmod(path, 0o600)
+    except OSError as exc:
+        raise JournalUnavailableError(f"Журнал операций недоступен для записи: {exc}") from exc
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def append_attempt(
+    *,
+    operation: str,
+    channel: str,
+    confirmation_id: str,
+    body_sha256: str,
+    body: dict,
+    sanction_remaining: int | None,
+) -> None:
+    """Тело проходит `redact_secrets` тем же вызовом, что и вывод ошибок — новой
+    точки маскирования не вводится (NFR-21)."""
+    _append(
+        {
+            "ts": _now(),
+            "event": "attempt",
+            "operation": operation,
+            "channel": channel,
+            "confirmation_id": confirmation_id,
+            "body_sha256": body_sha256,
+            "body": json.loads(redact_secrets(json.dumps(body, ensure_ascii=False))),
+            "sanction_remaining": sanction_remaining,
+        }
+    )
+
+
+def append_outcome(
+    *,
+    operation: str,
+    channel: str,
+    confirmation_id: str,
+    body_sha256: str,
+    result: str,
+    status_code: int | None,
+) -> None:
+    _append(
+        {
+            "ts": _now(),
+            "event": "outcome",
+            "operation": operation,
+            "channel": channel,
+            "confirmation_id": confirmation_id,
+            "body_sha256": body_sha256,
+            "result": result,
+            "status_code": status_code,
+        }
+    )

ktalk_cli/write_sanction.py

@@ -0,0 +1,187 @@
+"""ADR-016 §2: файловая санкция контура записи — срок, бюджет, независимые ключи.
+
+Механика ADR-014 §2 (fail-closed чтение, атомарная запись, права 0700/0600)
+переиспользована целиком; отличия продиктованы предметом — запись в боевой контур,
+а не установка пакета: срок и бюджет обязательны и конечны, ключ на каждую операцию.
+
+Проверки интерактивного терминала здесь нет намеренно: она живёт в `cli_sanction.py`.
+Модуль остаётся тестируемым, барьер — непроходимым из кода, потому что единственный
+путь к `grant()` снаружи пакета проходит через CLI.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+OPERATIONS = ("create_meeting", "cancel_meeting")
+
+# Дизайн-выбор, не измеренная величина (тот же класс решения, что CONFIRMATION_TTL):
+# обоснование и правило пересмотра — ADR-016-agent-executed-writes-spec.md §2.
+DEFAULT_HOURS = 8
+MAX_HOURS = 24 * 7
+DEFAULT_OPERATIONS = 3
+MAX_OPERATIONS = 20
+
+
+class SanctionError(Exception):
+    """Санкция не действует — код возврата несёт вызывающий CLI (ADR-016-spec §3)."""
+
+    def __init__(self, status: str) -> None:
+        super().__init__(f"Санкция на запись не действует: {status}")
+        self.status = status
+
+
+@dataclass(frozen=True)
+class SanctionState:
+    """`status`: active | absent | expired | exhausted. `absent` — общий исход для
+    отсутствия, отзыва и любой порчи файла (fail-closed, ADR-016 §4)."""
+
+    operation: str
+    status: str
+    expires_at: str | None = None
+    remaining: int | None = None
+
+    @property
+    def active(self) -> bool:
+        return self.status == "active"
+
+
+def sanction_path() -> Path:
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME") or None
+    root = Path(xdg_config_home) if xdg_config_home else Path.home() / ".config"
+    return root / "ktalk" / "write-sanction.toml"
+
+
+def _read_raw() -> dict:
+    path = sanction_path()
+    try:
+        mode = path.stat().st_mode
+        # SEC-006: права шире 0600 читаются как «санкции нет». Это не защита от
+        # владельца учётной записи (он и так может переписать файл), а защита от
+        # другого пользователя машины, которому файл стал доступен на запись.
+        if mode & 0o077:
+            return {}
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _parse_utc(raw: object) -> datetime | None:
+    if not isinstance(raw, str):
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def read_state(operation: str, *, now: datetime | None = None) -> SanctionState:
+    """Все условия обязаны выполниться одновременно; любое иное состояние — `absent`.
+    Различаются только `expired` и `exhausted`: они полезны оператору на его
+    собственной машине и не являются секретом (ADR-016-spec §2)."""
+    _check_operation(operation)
+    section = _read_raw().get(operation)
+    if not isinstance(section, dict) or section.get("allowed") is not True:
+        return SanctionState(operation, "absent")
+
+    expires_at = _parse_utc(section.get("expires_at"))
+    remaining = section.get("remaining")
+    if expires_at is None or not isinstance(remaining, int) or isinstance(remaining, bool):
+        return SanctionState(operation, "absent")
+
+    iso = expires_at.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    if expires_at <= (now or datetime.now(timezone.utc)):
+        return SanctionState(operation, "expired", iso, remaining)
+    if remaining <= 0:
+        return SanctionState(operation, "exhausted", iso, remaining)
+    return SanctionState(operation, "active", iso, remaining)
+
+
+def _check_operation(operation: str) -> None:
+    if operation not in OPERATIONS:
+        raise ValueError(f"Неизвестная операция: {operation!r}; допустимы {OPERATIONS}")
+
+
+def _write_raw(data: dict) -> None:
+    path = sanction_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+    lines: list[str] = []
+    for operation in OPERATIONS:
+        section = data.get(operation)
+        if not isinstance(section, dict):
+            continue
+        lines.append(f"[{operation}]")
+        for key, value in section.items():
+            if isinstance(value, bool):
+                lines.append(f"{key} = {str(value).lower()}")
+            elif isinstance(value, int):
+                lines.append(f"{key} = {value}")
+            else:
+                lines.append(f'{key} = "{value}"')
+        lines.append("")
+    tmp = path.with_name(f".{path.name}.tmp")
+    tmp.write_text("\n".join(lines), encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+
+
+def grant(
+    operation: str,
+    *,
+    hours: int = DEFAULT_HOURS,
+    operations: int = DEFAULT_OPERATIONS,
+    now: datetime | None = None,
+) -> SanctionState:
+    """Запрос за потолком отклоняется, а не усекается молча: усечение выдало бы
+    мандат, о котором оператор не просил и о котором он не знает."""
+    _check_operation(operation)
+    if not 1 <= hours <= MAX_HOURS:
+        raise ValueError(f"Срок санкции — от 1 до {MAX_HOURS} часов, получено: {hours}")
+    if not 1 <= operations <= MAX_OPERATIONS:
+        raise ValueError(
+            f"Бюджет санкции — от 1 до {MAX_OPERATIONS} операций, получено: {operations}"
+        )
+
+    moment = now or datetime.now(timezone.utc)
+    data = _read_raw()
+    data[operation] = {
+        "allowed": True,
+        "expires_at": _iso(moment + timedelta(hours=hours)),
+        "remaining": operations,
+        "granted_at": _iso(moment),
+    }
+    _write_raw(data)
+    return read_state(operation)
+
+
+def revoke(operation: str) -> None:
+    """Секция не удаляется — отзыв обязан быть наблюдаем в `status` (ADR-014 §2)."""
+    _check_operation(operation)
+    data = _read_raw()
+    section = data.get(operation)
+    data[operation] = {**(section if isinstance(section, dict) else {}), "allowed": False}
+    _write_raw(data)
+
+
+def consume(operation: str) -> int:
+    """Списание — до сетевой попытки, независимо от исхода (NFR-22)."""
+    state = read_state(operation)
+    if not state.active:
+        raise SanctionError(state.status)
+    data = _read_raw()
+    remaining = int(state.remaining or 0) - 1
+    data[operation] = {**data[operation], "remaining": remaining}
+    _write_raw(data)
+    return remaining
+
+
+def _iso(moment: datetime) -> str:
+    return moment.astimezone(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")