ktalk-cli 1.0.0__tar.gz → 2.0.0__tar.gz

{ktalk_cli-1.0.0 → ktalk_cli-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ktalk-cli
-Version: 1.0.0
+Version: 2.0.0
 Summary: CLI for accessing Kontur Talk (KTalk) recordings, transcripts and summaries
 Project-URL: Homepage, https://github.com/mdemyanov/ktalk-cli
 Project-URL: Repository, https://github.com/mdemyanov/ktalk-cli

{ktalk_cli-1.0.0 → ktalk_cli-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ktalk-cli"
-version = "1.0.0"
+version = "2.0.0"
 description = "CLI for accessing Kontur Talk (KTalk) recordings, transcripts and summaries"
 readme = "README.md"
 license = "MIT"

{ktalk_cli-1.0.0 → ktalk_cli-2.0.0}/src/ktalk_cli/cli.py

@@ -212,7 +212,7 @@ def _cmd_dashboard(reg: Registry, args) -> int:
     new = [r for r in recs if r["status"] == "new"]
     stats = {s: sum(1 for r in recs if r["status"] == s) for s in _STATUSES}
     if args.json:
-        _print_json({"new": new, "stats": stats})
+        _print_json({"new": new, "stats": stats, "last_synced": reg.get_meta("last_synced")})
         return 0
     print("# Дашборд KTalk\n")
     print("## Новые записи")

{ktalk_cli-1.0.0 → ktalk_cli-2.0.0}/src/ktalk_cli/cli_content.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import argparse
 import asyncio
+import json
 import sys
 from collections.abc import Awaitable, Callable
 
@@ -27,6 +28,7 @@ from ktalk_cli.formatters import (
     render_tool_output,
     render_transcript_output,
 )
+from ktalk_cli.transcript_identity import check_identity
 
 
 def register_subparsers(sub) -> None:
@@ -48,6 +50,12 @@ def register_subparsers(sub) -> None:
     p_tr.add_argument("--chunk", type=int, default=0)
     p_tr.add_argument("--chunk-size", type=int, default=30000)
     p_tr.add_argument("--json", action="store_true")
+    p_tr.add_argument(
+        "--no-verify-identity",
+        action="store_true",
+        help="Отключить сверку идентичности спикеров с участниками записи (NFR-17, "
+        "по умолчанию включена)",
+    )
 
     p_sum = sub.add_parser("get-summary", help="Полное саммари записи (сеть)")
     p_sum.add_argument("recording_key")
@@ -111,18 +119,64 @@ def cmd_get_recording(_reg, args: argparse.Namespace) -> int:
     return _run(_get_recording(args), format_recording, json_flag=args.json)
 
 
+async def _verify_transcript_identity(client: KTalkClient, recording_key: str, transcript: dict) -> dict:
+    """Оркестрация NFR-17 (ADR-023 §1, ред. 2a2f6e3): независимый вызов
+    `get_recording`; отказ вызова -> `not_checked` (маскирование той же функцией,
+    что и основная ошибка, NFR-5), не исключение наружу — основной результат
+    транскрипта возвращается в любом случае."""
+    try:
+        recording = await client.get_recording(recording_key)
+    except Exception as exc:  # noqa: BLE001 - not_checked, не отказ команды
+        return {"result": "not_checked", "reason": redact_secrets(str(exc))}
+    return check_identity(transcript, recording)
+
+
+def _render_transcript_with_identity(
+    output_text: str, identity_check: dict | None, *, json_flag: bool
+) -> str:
+    """Сборка вывода `get-transcript` (companion-спека «Оркестрация», шаг 4).
+    `identity_check is None` -> сверка отключена (`--no-verify-identity`), выводим
+    как раньше."""
+    if identity_check is None:
+        return output_text
+
+    if not json_flag:
+        line = f"[identity-check] {identity_check['result']}"
+        if "reason" in identity_check:
+            line += f" ({identity_check['reason']})"
+        return f"{output_text}\n{line}"
+
+    try:
+        parsed = json.loads(output_text)
+    except (json.JSONDecodeError, ValueError):
+        # `--chunk N` вне диапазона отдаёт нестрого-JSON текст — сверять нечего,
+        # печатаем как есть (companion-спека, edge case чанкинга).
+        return output_text
+
+    return json.dumps(
+        {"transcript": parsed, "identity_check": identity_check}, ensure_ascii=False, indent=2
+    )
+
+
 def cmd_get_transcript(_reg, args: argparse.Namespace) -> int:
-    async def _fetch() -> dict:
+    async def _fetch() -> tuple[dict, dict | None]:
         async with KTalkClient.from_settings(Settings()) as client:
-            return await client.get_transcript(args.recording_key)
+            data = await client.get_transcript(args.recording_key)
+            identity_check = None
+            if not args.no_verify_identity:
+                identity_check = await _verify_transcript_identity(
+                    client, args.recording_key, data
+                )
+            return data, identity_check
 
     try:
-        data = asyncio.run(_fetch())
+        data, identity_check = asyncio.run(_fetch())
     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 args.json else "markdown"
-    print(render_transcript_output(data, fmt, args.chunk, args.chunk_size))
+    output_text = render_transcript_output(data, fmt, args.chunk, args.chunk_size)
+    print(_render_transcript_with_identity(output_text, identity_check, json_flag=args.json))
     return 0
 
 

{ktalk_cli-1.0.0 → ktalk_cli-2.0.0}/src/ktalk_cli/formatters.py

@@ -123,7 +123,7 @@ def format_recording(data: dict) -> str:
     title = data.get("title", "Без названия")
     lines = [f"# {title}", ""]
 
-    lines.append(f"- **Ключ:** {data.get('id', data.get('key', 'N/A'))}")
+    lines.append(f"- **Ключ:** {data.get('id') or data.get('key') or 'N/A'}")
     lines.append(f"- **Дата:** {_format_datetime(data.get('createdDate'))}")
 
     created_by = data.get("createdBy")
@@ -162,7 +162,7 @@ def format_recordings_list(data: dict) -> str:
     ]
 
     for rec in entities:
-        rec_id = rec.get("id", rec.get("key", "N/A"))
+        rec_id = rec.get("id") or rec.get("key") or "N/A"
         title = rec.get("title", "Без названия")
         date = _format_datetime(rec.get("createdDate"))
         created_by = rec.get("createdBy") or {}

ktalk_cli-2.0.0/src/ktalk_cli/transcript_identity.py

@@ -0,0 +1,69 @@
+"""Сверка идентичности транскрипта (NFR-17, issue #5, ADR-023 §1 + companion-спека
+«Компоненты — NFR-17»): сверяет состав спикеров транскрипта с составом участников
+записи того же `recording_id` через независимый вызов `get_recording` — обнаруживает
+подмену транскрипта под конкуренцией (RES-006), не связанную с валидностью самого
+запроса.
+
+Чистые функции без сети и побочных эффектов — сеть (`client.get_recording`) и исход
+`not_checked` (отказ вызова) живут в оркестрации `cmd_get_transcript`
+(`cli_content.py`), не здесь.
+"""
+
+from __future__ import annotations
+
+
+def _identity_key(user_ref: dict | None) -> str | None:
+    """Идентификатор пользователя: `userInfo.key` или `.login` (именованный),
+    `anonymousId` или `anonymousName` (аноним), `None` если ссылка пуста — та же
+    приоритетность, что `_format_user_name(with_id=True)` в `formatters.py`, но
+    возвращает сырой токен для сравнения, не строку для вывода."""
+    if not user_ref:
+        return None
+    if user_ref.get("isAnonymous"):
+        return user_ref.get("anonymousId") or user_ref.get("anonymousName")
+    user_info = user_ref.get("userInfo")
+    if not user_info:
+        return None
+    return user_info.get("key") or user_info.get("login")
+
+
+def speaker_identities(transcript: dict) -> set[str]:
+    """Состав спикеров транскрипта: обход `tracks[]`, `speaker`, при отсутствии —
+    `diarizedSpeaker`; треки без обоих не подмешивают `None` в результат."""
+    identities: set[str] = set()
+    for track in transcript.get("tracks") or []:
+        speaker_ref = track.get("speaker") or track.get("diarizedSpeaker")
+        key = _identity_key(speaker_ref)
+        if key is not None:
+            identities.add(key)
+    return identities
+
+
+def participant_identities(recording: dict) -> set[str]:
+    """Состав участников записи: обход `recording["participants"]` (`TalkUserRef[]`)."""
+    identities: set[str] = set()
+    for participant in recording.get("participants") or []:
+        key = _identity_key(participant)
+        if key is not None:
+            identities.add(key)
+    return identities
+
+
+def check_identity(transcript: dict, recording: dict) -> dict:
+    """Четыре исхода (`not_checked` не формируется здесь — исход уровня оркестрации,
+    когда сам вызов `get_recording` падает):
+    - `inconclusive` — любое множество пусто, сравнивать не с чем;
+    - `match` — пересечение непусто;
+    - `mismatch` — оба множества непусты и не пересекаются (сигнатура RES-006)."""
+    transcript_speakers = speaker_identities(transcript)
+    recording_participants = participant_identities(recording)
+
+    if not transcript_speakers or not recording_participants:
+        return {"result": "inconclusive"}
+
+    result = "match" if transcript_speakers & recording_participants else "mismatch"
+    return {
+        "result": result,
+        "transcript_speakers": sorted(transcript_speakers),
+        "recording_participants": sorted(recording_participants),
+    }

{ktalk_cli-1.0.0 → ktalk_cli-2.0.0}/tests/test_cli_content.py

@@ -113,11 +113,15 @@ def test_get_recording_error_goes_to_stderr_with_nonzero_exit(httpx_mock: HTTPXM
 
 @pytest.mark.httpx_mock(assert_all_responses_were_requested=False)
 def test_get_transcript_json_default_returns_raw_json(httpx_mock: HTTPXMock, capsys):
+    """`--no-verify-identity`: предмет теста — форма raw-JSON транскрипта, не NFR-17
+    (ADR-023 §1 сделал сверку идентичности умолчанием — без флага здесь потребовался
+    бы и мок `get_recording`; отдельное покрытие умолчания-включено —
+    `tests/test_nfr17_identity_verification.py`)."""
     from ktalk_cli.cli import main
 
     httpx_mock.add_response(json={"status": "done", "tracks": []})
 
-    rc = main(["get-transcript", "REC-1", "--json"])
+    rc = main(["get-transcript", "REC-1", "--json", "--no-verify-identity"])
 
     assert rc == 0
     out = json.loads(capsys.readouterr().out)
@@ -126,11 +130,13 @@ def test_get_transcript_json_default_returns_raw_json(httpx_mock: HTTPXMock, cap
 
 @pytest.mark.httpx_mock(assert_all_responses_were_requested=False)
 def test_get_transcript_markdown_default(httpx_mock: HTTPXMock, capsys):
+    """`--no-verify-identity` — см. комментарий у `test_get_transcript_json_default_
+    returns_raw_json` выше: предмет здесь — markdown-рендер, не NFR-17."""
     from ktalk_cli.cli import main
 
     httpx_mock.add_response(json={"status": "done", "tracks": []})
 
-    rc = main(["get-transcript", "REC-1"])
+    rc = main(["get-transcript", "REC-1", "--no-verify-identity"])
 
     assert rc == 0
     assert "Транскрипт" in capsys.readouterr().out

ktalk_cli-2.0.0/tests/test_fr41_last_synced.py

@@ -0,0 +1,243 @@
+"""AT-design: FR-41 — наблюдаемость момента последней синхронизации реестра
+(`content/40-architecture/at-design-adr023-open-issues.md`, раздел «FR-41»).
+
+Покрывает 3 AC FR-41 из `content/30-requirements/registry-sync-observability.md`
+(BA-014) через `#### Scenario:` капабилити-спеки `openspec/specs/registry-sync-window/
+spec.md`, раздел «The last sync moment is exposed by a reading command, not only
+recorded internally»:
+- FR41-AC1 — `dashboard --json` после `sync` отдаёт то же значение, что записал `sync`.
+- FR41-AC2 — свежий реестр без единого `sync` -> ключ `last_synced` присутствует,
+  значение явный `null`, не пропуск поля.
+- FR41-AC3 — серия чтений `dashboard --json` не меняет статусы записей реестра.
+
+Решение SA (ADR-023 §2): `last_synced` — поле ВЕРХНЕГО уровня JSON-ответа `dashboard
+--json` (не внутри `stats` — тот однородный `{статус: count}`), значение
+`Registry.get_meta("last_synced")` как есть, формат ISO-8601 `YYYY-MM-DD` (точность
+до дня, `cli_sync.py:126` не меняется).
+
+Красные по замыслу: `_cmd_dashboard` (`cli.py:210`) сегодня печатает только `{"new":
+new, "stats": stats}` — поля `last_synced` в ответе нет вовсе. Стабы падают на
+`assert`/`KeyError` через `out["last_synced"]`, не на импорте — модуль и функция уже
+существуют, меняется состав их JSON-ответа. Реализация — DEV-019 (после этого файла).
+
+Классы обязательного покрытия (контракт QA-author):
+- **Испорченный/опечатанный ввод** — N/A для FR-41: `dashboard --json` не принимает от
+  пользователя ни идентификатор записи, ни сегмент URL, ни поисковый запрос — команда
+  без позиционных аргументов, читает весь реестр целиком. Испорченный `--db` путь —
+  предмет других файлов (не FR-41 конкретно), не дублируется здесь.
+- **Замаскированный отказ** — FR41-AC2 и есть этот класс дословно: `null` должен быть
+  ЯВНЫМ значением ключа, не тихим пропуском поля (что было бы неотличимо от дефекта
+  сериализации) и не тихой заменой на другое значение по умолчанию. Отдельный
+  усиленный тест ниже проверяет это конкретно на уровне текста ответа, не только на
+  уровне распарсенного словаря.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import date, timedelta
+from pathlib import Path
+
+
+def _seed_mixed_statuses(db: Path) -> None:
+    from ktalk_cli.registry import Registry
+
+    today = date.today().isoformat()
+    with Registry(db) as reg:
+        reg.upsert_recording(
+            {"recording_id": "a", "name": "Standup", "date": today}, now=today
+        )
+        reg.upsert_recording(
+            {"recording_id": "b", "name": "1-1", "date": today}, now=today
+        )
+        reg.set_status("b", "done")
+        reg.upsert_recording(
+            {"recording_id": "c", "name": "Retro", "date": today}, now=today
+        )
+        reg.set_status("c", "partial")
+        reg.upsert_recording(
+            {"recording_id": "d", "name": "Old", "date": today}, now=today
+        )
+        reg.set_status("d", "skipped")
+
+
+def _run_sync(db: Path, monkeypatch, httpx_mock, capsys) -> None:
+    """Реальный `ktalk sync` через CLI (не прямой `reg.set_meta`) — FR41-AC1 сверяет
+    ответ `dashboard --json` со значением, которое сама команда `sync` записала,
+    воспроизводя путь AC дословно: "сравнение значения из --json-ответа со значением
+    Registry.get_meta("last_synced") после sync". Явно вычищает буфер `capsys` после
+    себя — иначе собственный JSON-вывод `sync` конкатенируется с последующим выводом
+    `dashboard --json` в одном захвате и ломает `json.loads` `Extra data`-ошибкой,
+    маскируя реальную причину падения теста своей собственной (control-flow
+    ошибка теста, не отсутствующее поведение под тестом)."""
+    monkeypatch.setenv("KTALK_BASE_URL", "https://test.ktalk.ru")
+    monkeypatch.setenv("KTALK_SESSION_TOKEN", "tok-fr41")
+    monkeypatch.delenv("KTALK_PERSONAL_API_KEY", raising=False)
+    monkeypatch.delenv("KTALK_REGISTRY_DB", raising=False)
+
+    httpx_mock.add_response(json={"recordings": []})  # одна пустая страница -> sync done
+
+    from ktalk_cli.cli import main
+
+    rc = main(["--db", str(db), "sync", "--days", "7", "--json"])
+    assert rc == 0, "предпосылка теста: sync должен пройти успешно"
+    capsys.readouterr()  # вычищает собственный вывод sync перед вызовами dashboard
+
+
+# === FR41-AC1: значение после sync совпадает с записанным ==================================
+
+
+def test_fr41_ac1_dashboard_json_last_synced_matches_registry_get_meta_after_sync(
+    tmp_path, monkeypatch, httpx_mock, capsys
+):
+    from ktalk_cli.cli import main
+    from ktalk_cli.registry import Registry
+
+    db = tmp_path / "r.db"
+    _run_sync(db, monkeypatch, httpx_mock, capsys)
+
+    with Registry(db) as reg:
+        recorded = reg.get_meta("last_synced")
+    assert recorded is not None, "предпосылка: sync должен был записать last_synced"
+
+    rc = main(["--db", str(db), "dashboard", "--json"])
+    out = json.loads(capsys.readouterr().out)
+
+    assert rc == 0
+    assert "last_synced" in out, (
+        "FR41-AC1: `dashboard --json` обязан отдавать `last_synced` верхнего уровня "
+        f"после хотя бы одной синхронизации, получен ответ без ключа: {out}"
+    )
+    assert out["last_synced"] == recorded, (
+        "FR41-AC1: значение в ответе должно совпадать со значением, которое записала "
+        f"сама sync — записано {recorded!r}, в ответе {out.get('last_synced')!r}"
+    )
+
+
+def test_fr41_ac1_last_synced_is_top_level_not_nested_in_stats(
+    tmp_path, monkeypatch, httpx_mock, capsys
+):
+    """Решение SA (ADR-023 §2): поле верхнего уровня, НЕ внутри `stats` (тот
+    однородный `{статус: count}` — чужеродное поле ломает эту форму для потребителя,
+    итерирующего по нему)."""
+    from ktalk_cli.cli import main
+
+    db = tmp_path / "r.db"
+    _run_sync(db, monkeypatch, httpx_mock, capsys)
+
+    rc = main(["--db", str(db), "dashboard", "--json"])
+    out = json.loads(capsys.readouterr().out)
+
+    assert rc == 0
+    assert "last_synced" not in out.get("stats", {}), (
+        "FR41-AC1 (форма ответа, ADR-023 §2): `last_synced` не должен жить внутри "
+        f"`stats` — обнаружен там: {out.get('stats')}"
+    )
+
+
+# === FR41-AC2: свежий реестр без sync -> явный null, не пропуск ключа ======================
+
+
+def test_fr41_ac2_never_synced_registry_reports_explicit_null_not_missing_key(
+    tmp_path, capsys
+):
+    from ktalk_cli.cli import main
+
+    db = tmp_path / "r.db"  # реестр создаётся с нуля, sync ни разу не вызывался
+
+    rc = main(["--db", str(db), "dashboard", "--json"])
+    out = json.loads(capsys.readouterr().out)
+
+    assert rc == 0
+    assert "last_synced" in out, (
+        "FR41-AC2: ключ `last_synced` обязан присутствовать в ответе даже без единой "
+        f"синхронизации — тихий пропуск поля запрещён требованием, получен ответ: {out}"
+    )
+    assert out["last_synced"] is None, (
+        "FR41-AC2: без единой синхронизации значение обязано быть явным `null`, "
+        f"получено {out['last_synced']!r}"
+    )
+
+
+def test_fr41_ac2_masked_failure_null_is_literal_json_null_not_omitted_field(
+    tmp_path, capsys
+):
+    """Класс «замаскированный отказ»: наивная реализация могла бы тихо ОПУСТИТЬ ключ,
+    когда `get_meta` возвращает `None` (обычный паттерн `if value: payload[...] = ...`)
+    — снаружи это неотличимо от дефекта сериализации, тот самый риск, который AC2
+    называет прямым текстом. Проверяем на уровне сырого текста stdout, не только
+    распарсенного словаря — исключает случай, где парсер молча подставляет `None` за
+    отсутствующий ключ и маскирует разницу между "ключа нет" и "ключ есть, там null"."""
+    from ktalk_cli.cli import main
+
+    db = tmp_path / "r.db"
+
+    rc = main(["--db", str(db), "dashboard", "--json"])
+    raw = capsys.readouterr().out
+
+    assert rc == 0
+    assert '"last_synced"' in raw, (
+        "FR41-AC2 (замаскированный отказ): литерал ключа `\"last_synced\"` обязан "
+        f"присутствовать в сыром JSON-тексте ответа, получено: {raw!r}"
+    )
+
+
+# === FR41-AC3: серия чтений не мутирует статусы записей =====================================
+
+
+def test_fr41_ac3_repeated_dashboard_json_calls_do_not_change_any_recording_status(
+    tmp_path, monkeypatch, httpx_mock, capsys
+):
+    from ktalk_cli.cli import main
+    from ktalk_cli.registry import Registry
+
+    db = tmp_path / "r.db"
+    _run_sync(db, monkeypatch, httpx_mock, capsys)  # last_synced присутствует, не только пустой реестр
+    _seed_mixed_statuses(db)
+
+    with Registry(db) as reg:
+        before = {r["recording_id"]: r["status"] for r in reg.list_recordings()}
+
+    for _ in range(5):
+        rc = main(["--db", str(db), "dashboard", "--json"])
+        capsys.readouterr()
+        assert rc == 0
+
+    with Registry(db) as reg:
+        after = {r["recording_id"]: r["status"] for r in reg.list_recordings()}
+
+    assert after == before, (
+        "FR41-AC3: пятикратный вызов `dashboard --json` (в т.ч. читающего "
+        f"`last_synced`) не должен менять статусы записей — было {before}, стало {after}"
+    )
+
+
+def test_fr41_ac3_repeated_dashboard_json_calls_do_not_change_sync_meta(
+    tmp_path, monkeypatch, httpx_mock, capsys
+):
+    """Узкая версия AC3: сам `last_synced`/`sync_count` в `meta` — не только статусы
+    записей — не должны сдвигаться от чтения (не только не регрессировать в другой
+    статус, но и не «обновляться» будто чтение — это ползучий sync)."""
+    from ktalk_cli.cli import main
+    from ktalk_cli.registry import Registry
+
+    db = tmp_path / "r.db"
+    _run_sync(db, monkeypatch, httpx_mock, capsys)
+
+    with Registry(db) as reg:
+        synced_before = reg.get_meta("last_synced")
+        count_before = reg.get_meta("sync_count")
+
+    for _ in range(3):
+        main(["--db", str(db), "dashboard", "--json"])
+        capsys.readouterr()
+
+    with Registry(db) as reg:
+        synced_after = reg.get_meta("last_synced")
+        count_after = reg.get_meta("sync_count")
+
+    assert synced_after == synced_before
+    assert count_after == count_before, (
+        "FR41-AC3: чтение `dashboard --json` не должно инкрементировать `sync_count` "
+        f"— было {count_before}, стало {count_after}"
+    )