sud-cli 0.1.1__py3-none-any.whl

sud_cli/backup.py

@@ -0,0 +1,256 @@
+"""история §5 (S-85): backup / verify / restore snapshot'а store.db.
+
+sqlite stdlib, без внешних процессов:
+- create — ``sqlite3.Connection.backup`` (горячий снимок, не cp под WAL),
+  файл 0600 + sha256 sidecar; путь снимка пишется в ``meta`` (S-86 читает
+  «last backup» оттуда, а не из воздуха);
+- verify — PRAGMA integrity_check + quick_check + список таблиц схемы;
+  sidecar сверяется, если лежит рядом;
+- restore — деструктив: без явного подтверждения не делает ничего, превью
+  показывает, что будет перезаписано (путь, размер, таблица->кол-во строк
+  текущей БД). Живой state в тестах не трогается: вызывающий передаёт tmp-dir.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .db import _db_path, get_connection, init_db, set_meta
+
+BACKUP_PREFIX = "store-backup-"
+SIDECAR_SUFFIX = ".sha256"
+META_LAST_BACKUP_KEY = "last_backup_path"
+META_LAST_BACKUP_SHA_KEY = "last_backup_sha256"
+
+RESTORE_DISCLAIMER = (
+    "restore перезаписывает store.db state-dir целиком: всё, что было создано "
+    "после снимка, теряется. Подтверждение --yes обязательно."
+)
+
+
+def _now_stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def default_backup_dir(state_dir: Any) -> Path:
+    return Path(state_dir) / "backups"
+
+
+def snapshot_tables(path: Path) -> Dict[str, int]:
+    """таблица -> число строк (только пользовательские таблицы, без sqlite_INTERNAL)."""
+    conn = sqlite3.connect(str(path))
+    try:
+        rows = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%' ORDER BY name ASC"
+        ).fetchall()
+        out = {}
+        for (name,) in rows:
+            out[name] = int(conn.execute(f"SELECT COUNT(*) FROM {name}").fetchone()[0])
+        return out
+    finally:
+        conn.close()
+
+
+def create_backup(state_dir: Any, out: Optional[Path] = None) -> Dict[str, Any]:
+    """Горячий снимок store.db -> timestamped файл 0600 + sha256 sidecar."""
+    state_dir = Path(state_dir)
+    init_db(state_dir)
+    src_path = _db_path(state_dir)
+    if not src_path.is_file():
+        raise FileNotFoundError(f"store.db не найден: {src_path}")
+
+    if out is None:
+        dest_dir = default_backup_dir(state_dir)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        target = dest_dir / f"{BACKUP_PREFIX}{_now_stamp()}.db"
+    else:
+        target = Path(out)
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+    src = sqlite3.connect(str(src_path))
+    try:
+        dst = sqlite3.connect(str(target))
+        try:
+            with dst:
+                src.backup(dst)
+        finally:
+            dst.close()
+    finally:
+        src.close()
+
+    # 0600 до того, как появится sidecar: снимок содержит ПДн дела.
+    os.chmod(target, 0o600)
+    digest = _sha256_file(target)
+    sidecar = target.with_name(target.name + SIDECAR_SUFFIX)
+    sidecar.write_text(f"{digest}  {target.name}\n", encoding="utf-8")
+    os.chmod(sidecar, 0o600)
+
+    conn = get_connection(state_dir)
+    try:
+        set_meta(conn, META_LAST_BACKUP_KEY, str(target))
+        set_meta(conn, META_LAST_BACKUP_SHA_KEY, digest)
+    finally:
+        conn.close()
+
+    return {
+        "path": str(target),
+        "sidecar": str(sidecar),
+        "sha256": digest,
+        "bytes": target.stat().st_size,
+        "mode": oct(0o600),
+        "tables": snapshot_tables(target),
+        "source": str(src_path),
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def read_sidecar(backup: Path) -> Optional[str]:
+    sidecar = backup.with_name(backup.name + SIDECAR_SUFFIX)
+    if not sidecar.is_file():
+        return None
+    text = sidecar.read_text(encoding="utf-8").strip()
+    return text.split()[0] if text else None
+
+
+def verify_backup(path: Any) -> Dict[str, Any]:
+    """integrity_check + quick_check + таблицы схемы; sidecar, если есть рядом."""
+    backup = Path(path)
+    if not backup.is_file():
+        raise FileNotFoundError(f"backup не найден: {backup}")
+    integrity = quick = None
+    conn = sqlite3.connect(str(backup))
+    try:
+        integrity = conn.execute("PRAGMA integrity_check").fetchone()[0]
+        quick = conn.execute("PRAGMA quick_check").fetchone()[0]
+        tables = [r[0] for r in conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%' ORDER BY name ASC").fetchall()]
+        schema_version = None
+        if "meta" in tables:
+            row = conn.execute(
+                "SELECT value FROM meta WHERE key='schema_version'").fetchone()
+            schema_version = row[0] if row else None
+    finally:
+        conn.close()
+
+    recorded = read_sidecar(backup)
+    actual = _sha256_file(backup)
+    return {
+        "path": str(backup),
+        "bytes": backup.stat().st_size,
+        "integrity_check": integrity,
+        "quick_check": quick,
+        "integrity_ok": integrity == "ok",
+        "quick_ok": quick == "ok",
+        "tables": tables,
+        "table_count": len(tables),
+        "schema_version": schema_version,
+        "sha256": actual,
+        "sidecar_sha256": recorded,
+        "sidecar_match": None if recorded is None else (recorded == actual),
+    }
+
+
+def restore_preview(state_dir: Any, path: Any) -> Dict[str, Any]:
+    """Что будет перезаписано: путь живой БД, её размер/таблицы + снимок."""
+    state_dir = Path(state_dir)
+    live = _db_path(state_dir)
+    info: Dict[str, Any] = {
+        "target": str(live),
+        "target_exists": live.is_file(),
+        "target_bytes": live.stat().st_size if live.is_file() else 0,
+        "target_tables": snapshot_tables(live) if live.is_file() else {},
+        "source": str(path),
+        "source_tables": {},
+    }
+    if Path(path).is_file():
+        info["source_tables"] = snapshot_tables(Path(path))
+    return info
+
+
+def restore_backup(state_dir: Any, path: Any, confirmed: bool = False,
+                   actor: str = "cli") -> Dict[str, Any]:
+    """Перезапись store.db из снимка. Без confirmed ничего не меняется."""
+    state_dir = Path(state_dir)
+    backup = Path(path)
+    preview = restore_preview(state_dir, backup)
+    if not confirmed:
+        return {
+            "status": "needs_confirmation",
+            "detail": "restore деструктивен: требуется --yes; изменится store.db "
+                      "целиком — всё, что создано после снимка, будет потеряно",
+            "preview": preview,
+            "disclaimer": RESTORE_DISCLAIMER,
+        }
+    if not backup.is_file():
+        raise FileNotFoundError(f"backup не найден: {backup}")
+    check = verify_backup(backup)
+    if not (check["integrity_ok"] and check["quick_ok"]):
+        raise sqlite3.DatabaseError(
+            f"backup не прошёл integrity_check/quick_check: "
+            f"{check['integrity_check']}/{check['quick_check']}")
+
+    state_dir.mkdir(parents=True, exist_ok=True)
+    target = _db_path(state_dir)
+    src = sqlite3.connect(str(backup))
+    try:
+        dst = sqlite3.connect(str(target))
+        try:
+            with dst:
+                src.backup(dst)
+        finally:
+            dst.close()
+    finally:
+        src.close()
+    os.chmod(target, 0o600)
+    conn = get_connection(state_dir)
+    try:
+        set_meta(conn, "last_restore_at", datetime.now(timezone.utc).isoformat())
+        set_meta(conn, "last_restore_source", str(backup))
+    finally:
+        conn.close()
+    return {
+        "status": "restored",
+        "target": str(target),
+        "source": str(backup),
+        "actor": actor,
+        "tables_after": snapshot_tables(target),
+        "disclaimer": RESTORE_DISCLAIMER,
+    }
+
+
+def last_backup(state_dir: Any) -> Dict[str, Any]:
+    """Последний снимок из meta (S-86): путь+sha, которые мы сами записали."""
+    state_dir = Path(state_dir)
+    init_db(state_dir)
+    conn = get_connection(state_dir)
+    try:
+        from .db import get_meta
+
+        path = get_meta(conn, META_LAST_BACKUP_KEY)
+        sha = get_meta(conn, META_LAST_BACKUP_SHA_KEY)
+    finally:
+        conn.close()
+    exists = bool(path) and Path(str(path)).is_file()
+    recorded = read_sidecar(Path(str(path))) if exists else None
+    return {
+        "path": path,
+        "sha256": sha,
+        "exists": exists,
+        # verified — sidecar рядом и совпал с записанным в meta; None, если
+        # снимка нет: «не проверялось», а не «проверено и плохо».
+        "verified": None if not exists else bool(recorded and recorded == sha),
+    }

sud_cli/calendar_ics.py

@@ -0,0 +1,191 @@
+"""W6a §3 (S-28): экспорт дедлайнов в RFC 5545 (ICS).
+
+Источник — deadline_states computed/confirmed (the wave), по последнему состоянию
+на пару (case_id, deadline_key); waived и due_at=NULL не экспортируются.
+Конверт детерминирован: DTSTAMP выводится из due-даты, поэтому повторный
+экспорт тех же состояний даёт побайтово тот же файл (UID стабильны —
+требование идемпотентности из ТЗ).
+
+Формат (RFC 5545):
+- CRLF переносы; строки не длиннее 75 октетов — длинные фолдятся continuation
+  пробелом, разбивка идёт по границам символов utf-8;
+- спецсимволы TEXT-значений экранируются: ``\\\\`` -> ``\\\\\\\\``, ``;`` -> ``\\\\;``,
+  ``,`` -> ``\\\\,``, перевод строки -> ``\\\\n``;
+- DTSTART/DTEND — локальное время суда (Europe/Moscow, 09:00, +1 час) с явным
+  TZID и блоком VTIMEZONE: календарь без таймзоны агент прочтёт как UTC;
+- VALARM -P1D ставится ТОЛЬКО на confirmed: напоминать за сутки по unverified
+  вычисленному сроку — давление на оператора, а не факт (anti-laches).
+"""
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Optional, Tuple
+
+PRODID = "-//sud-cli//DEADLINES RU 2.11.0//EN"
+TZID = "Europe/Moscow"
+DUE_HOUR = 9  # процессуальные сроки истекают в конце дня; событие ставим на утро суда
+LINE_LEN = 75  # октетов, RFC 5545 3.1
+EXPORT_STATES = ("computed", "confirmed")
+
+_VTIMEZONE = (
+    "BEGIN:VTIMEZONE",
+    f"TZID:{TZID}",
+    "BEGIN:STANDARD",
+    "DTSTART:20141026T000000",
+    "TZOFFSETFROM:+0400",
+    "TZOFFSETTO:+0300",
+    "TZNAME:MSK",
+    "END:STANDARD",
+    "END:VTIMEZONE",
+)
+
+
+def _esc(text) -> str:
+    out = str(text if text is not None else "")
+    out = out.replace("\\", "\\\\")
+    out = out.replace(";", "\\;")
+    out = out.replace(",", "\\,")
+    out = out.replace("\r\n", "\\n").replace("\n", "\\n")
+    return out
+
+
+def _fold(line: str) -> list[str]:
+    """Разбить строку на куски <= 75 октетов; continuation-строки с ведущим
+    пробелом (RFC 5545 3.1), разбивка по границам символов utf-8."""
+    if len(line.encode("utf-8")) <= LINE_LEN:
+        return [line]
+    pieces: list[str] = []
+    current: list[str] = []
+    current_len = 0
+    limit = LINE_LEN
+    for ch in line:
+        ch_len = len(ch.encode("utf-8"))
+        if current_len + ch_len > limit:
+            pieces.append("".join(current))
+            current = [ch]
+            current_len = ch_len
+            limit = LINE_LEN - 1  # continuation-строка начинается с пробела
+        else:
+            current.append(ch)
+            current_len += ch_len
+    if current:
+        pieces.append("".join(current))
+    return [pieces[0]] + [" " + p for p in pieces[1:]]
+
+
+def _line(name: str, value: str) -> list[str]:
+    return _fold(f"{name}:{value}")
+
+
+def event_uid(case_id: str, deadline_key: str) -> str:
+    """Стабильный UID: пара (дело, ключ) — не id строки истории."""
+    return f"{case_id}-{deadline_key}@sud-cli"
+
+
+def _latest_per_key(states):
+    latest = {}
+    for s in states:
+        key = (s.get("case_id"), s.get("deadline_key"))
+        try:
+            sid = int(s.get("id") or 0)
+        except (TypeError, ValueError):
+            sid = 0
+        prev = latest.get(key)
+        if prev is None or sid >= int(prev.get("id") or 0):
+            latest[key] = s
+    return latest
+
+
+def _describe(state: dict) -> str:
+    basis = state.get("basis")
+    if isinstance(basis, dict):
+        basis_txt = "; ".join(f"{k}={v}" for k, v in sorted(basis.items()))
+    elif basis:
+        basis_txt = str(basis)
+    else:
+        basis_txt = "-"
+    parts = [f"case={state.get('case_id')}", f"key={state.get('deadline_key')}",
+             f"state={state.get('state')}", f"basis: {basis_txt}"]
+    if state.get("evidence_note"):
+        parts.append(f"evidence: {state['evidence_note']}")
+    if state.get("confirmed_by"):
+        parts.append(f"confirmed_by: {state['confirmed_by']}")
+    return " | ".join(parts)
+
+
+def build_ics(states, today: Optional[date] = None, days: int = 60) -> Tuple[str, list[dict]]:
+    """VCALENDAR-текст (CRLF) + список событий; пустой вход = валидный пустой календарь."""
+    today = today or date.today()
+    horizon = today + timedelta(days=days)
+    events_meta: list[dict] = []
+    body: list[str] = []
+    chosen = []
+    for (case_id, key), s in sorted(_latest_per_key(states).items(),
+                                    key=lambda kv: (str(kv[0][0]), str(kv[0][1]))):
+        if s.get("state") not in EXPORT_STATES:
+            continue
+        raw_due = s.get("due_at")
+        if not raw_due:
+            continue
+        try:
+            due = date.fromisoformat(str(raw_due)[:10])
+        except ValueError:
+            continue
+        if not (today <= due <= horizon):
+            continue
+        chosen.append((case_id, key, s, due))
+
+    for case_id, key, s, due in chosen:
+        uid = event_uid(str(case_id), str(key))
+        stamp = f"{due.strftime('%Y%m%d')}T000000Z"
+        start = f"{due.strftime('%Y%m%d')}T{DUE_HOUR:02d}0000"
+        # DTEND = DTSTART + 1 час; дата та же, поскольку DUE_HOUR+1 < 24.
+        end = f"{due.strftime('%Y%m%d')}T{DUE_HOUR + 1:02d}0000"
+        lines: list[str] = ["BEGIN:VEVENT"]
+        lines += _line("UID", _esc(uid))
+        lines += _line("DTSTAMP", stamp)
+        lines += _line("DTSTART;TZID=" + TZID, start)
+        lines += _line("DTEND;TZID=" + TZID, end)
+        lines += _line("SUMMARY", _esc(f"deadline: {key} {case_id}"))
+        lines += _line("DESCRIPTION", _esc(_describe(s)))
+        lines += _line("STATUS", "CONFIRMED")
+        if s.get("state") == "confirmed":
+            lines += ["BEGIN:VALARM"]
+            lines += _line("ACTION", "DISPLAY")
+            lines += _line("TRIGGER", "-P1D")
+            lines += _line("DESCRIPTION", _esc(f"deadline reminder: {key} {case_id}"))
+            lines += ["END:VALARM"]
+        lines.append("END:VEVENT")
+        body += lines
+        events_meta.append({
+            "uid": uid,
+            "case_id": case_id,
+            "deadline_key": key,
+            "due_at": due.isoformat(),
+            "state": s.get("state"),
+            "alarm": s.get("state") == "confirmed",
+        })
+
+    out: list[str] = ["BEGIN:VCALENDAR"]
+    out += _line("VERSION", "2.0")
+    out += _line("PRODID", PRODID)
+    out += _line("CALSCALE", "GREGORIAN")
+    out += _line("METHOD", "PUBLISH")
+    out += list(_VTIMEZONE)
+    out += body
+    out.append("END:VCALENDAR")
+    text = "\r\n".join(out) + "\r\n"
+    return text, events_meta
+
+
+def ics_for_state_dir(state_dir, days: int = 60,
+                      today: Optional[date] = None) -> Tuple[str, list[dict]]:
+    from sud_cli.db import get_connection, init_db, list_all_deadline_states
+
+    init_db(state_dir)
+    conn = get_connection(state_dir)
+    try:
+        states = list_all_deadline_states(conn)
+    finally:
+        conn.close()
+    return build_ics(states, today=today, days=days)

sud_cli/case_diff.py

@@ -0,0 +1,165 @@
+"""Build a version diff over two saved snapshots — mirrors case-search semantics.
+
+case-search has ``diff_snapshots`` in ``case_search/diff.py:59`` but never
+exposes it: no CLI subcommand calls it and ``public_api.py`` does not re-export
+it (verified by grep over the whole package and by ``case-search --help``).
+sud-cli therefore implements the same field set on its own, reading the two
+snapshot JSON files that the import commands already write into the state
+directory. case-search itself is untouched.
+
+The compared fields are copied from ``case_search.diff._SCALARS`` so the two
+implementations agree on what counts as a change.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+# Copied from case_search/diff.py::_SCALARS.
+SCALAR_FIELDS: Tuple[Tuple[str, Tuple[str, ...]], ...] = (
+    ("status", ("status",)),
+    ("court", ("court",)),
+    ("judge", ("judge",)),
+    ("updated_at", ("updated_at",)),
+    ("next_hearing.date", ("next_hearing", "date")),
+    ("next_hearing.time", ("next_hearing", "time")),
+    ("next_hearing.hall", ("next_hearing", "hall")),
+    ("next_hearing.type", ("next_hearing", "type")),
+    ("last_event.date", ("last_event", "date")),
+    ("last_event.event_type", ("last_event", "event_type")),
+    ("last_event.document_url", ("last_event", "document_url")),
+)
+
+
+class DiffError(Exception):
+    """A snapshot file is missing, unreadable or not a case snapshot."""
+
+
+def _dig(payload: Dict[str, Any], path: Tuple[str, ...]) -> Any:
+    current: Any = payload
+    for key in path:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(key)
+    return current
+
+
+def _load(path: Path) -> Dict[str, Any]:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise DiffError(f"cannot read snapshot: {exc}") from exc
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise DiffError(f"snapshot is not valid JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise DiffError("snapshot must be a JSON object")
+    return payload
+
+
+def _snapshot_payload(path: Path) -> Dict[str, Any]:
+    """Return the snapshot object, unwrapping an ``auto-import`` envelope.
+
+    ``auto-import`` wraps its result as ``{"snapshot": {...}, "extensions": ...}``
+    while ``sudrf-import`` writes the snapshot at the top level. Accepting both
+    keeps the command usable regardless of which importer produced the file.
+    """
+    payload = _load(path)
+    inner = payload.get("snapshot")
+    if isinstance(inner, dict):
+        return inner
+    return payload
+
+
+def _parties(payload: Dict[str, Any]) -> Dict[str, List[str]]:
+    parties = payload.get("parties")
+    if not isinstance(parties, dict):
+        return {"plaintiff": [], "respondent": [], "third_parties": []}
+    return {
+        key: list(parties.get(key) or [])
+        for key in ("plaintiff", "respondent", "third_parties")
+    }
+
+
+def _timeline_index(payload: Dict[str, Any]) -> Dict[Tuple[str, str], bool]:
+    index: Dict[Tuple[str, str], bool] = {}
+    for event in payload.get("events_timeline") or []:
+        if not isinstance(event, dict):
+            continue
+        date = event.get("date")
+        name = event.get("name")
+        if date is None or name is None:
+            continue
+        index[(str(date), str(name))] = bool(event.get("published"))
+    return index
+
+
+def diff_case_snapshots(
+    old_path: Path, new_path: Path
+) -> Dict[str, Any]:
+    """Compare two saved snapshots of the same case.
+
+    Returns a dict with ``changed``, ``changes`` (path/before/after) and
+    ``added_removed_events``. An unchanged pair yields ``changed: False`` with
+    empty lists rather than an error, because "nothing moved" is a legitimate
+    answer to the question.
+    """
+    old = _snapshot_payload(old_path)
+    new = _snapshot_payload(new_path)
+
+    old_number = str(old.get("case_number") or "")
+    new_number = str(new.get("case_number") or "")
+    if not old_number or not new_number:
+        raise DiffError("snapshot has no case_number")
+
+    # Check identity *before* comparing: a field-by-field report across two
+    # different cases would be noise dressed up as a diff.
+    if old_number != new_number:
+        raise DiffError(
+            f"snapshots belong to different cases: {old_number} vs {new_number}"
+        )
+
+    changes: List[Dict[str, Any]] = []
+    for path, keys in SCALAR_FIELDS:
+        before = _dig(old, keys)
+        after = _dig(new, keys)
+        if before != after:
+            changes.append({"path": path, "before": before, "after": after})
+
+    before_parties = _parties(old)
+    after_parties = _parties(new)
+    for role in ("plaintiff", "respondent", "third_parties"):
+        if before_parties[role] != after_parties[role]:
+            changes.append({
+                "path": f"parties.{role}",
+                "before": before_parties[role],
+                "after": after_parties[role],
+            })
+
+    old_tl = _timeline_index(old)
+    new_tl = _timeline_index(new)
+    timeline_changes: List[Dict[str, Any]] = []
+    for key in sorted(set(old_tl) | set(new_tl)):
+        was, now = old_tl.get(key), new_tl.get(key)
+        if was != now:
+            timeline_changes.append({
+                "date": key[0],
+                "name": key[1],
+                "before": was,
+                "after": now,
+            })
+
+    return {
+        "case_number": new_number,
+        "changed": bool(changes or timeline_changes),
+        "changes": sorted(changes, key=lambda c: c["path"]),
+        "timeline_changes": timeline_changes,
+        "compared_fields": len(SCALAR_FIELDS) + 3,
+        "source": {
+            "old": str(old_path),
+            "new": str(new_path),
+        },
+    }