sud-cli 0.1.1__py3-none-any.whl

sud_cli/readiness.py

@@ -0,0 +1,234 @@
+"""Live-readiness self-check for AI agents driving sud-cli.
+
+An agent that only reads ``--help`` cannot tell that every court command needs
+``SUD_CLI_BRIDGE_LIVE=1``, that ``lookup`` needs ``--source`` or that the case
+reference uses a two-digit year. Each of those was discovered by hand on
+2026-10-09, at the cost of a full debugging session. This module answers the
+same questions in one call, without contacting any court host.
+
+Everything here is local: the checks only inspect configuration, the
+case-search binary on PATH, and the optional Camofox runtime on loopback.
+No court request is made, so the check is safe to run before every session.
+
+``check_live_readiness`` returns a mapping with one entry per concern, each
+carrying ``ok``, ``detail`` and — where it applies — ``remedy``, so an agent
+can act on the output without reading the source.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Any, Dict, Optional
+from urllib.request import urlopen
+from urllib.error import URLError
+
+#: Environment variable that opts the bridge into live court access.
+LIVE_ENV_VAR = "SUD_CLI_BRIDGE_LIVE"
+
+#: Environment variable that routes case-search at an external Camofox
+#: runtime. Required on this host: the in-process browser cannot initialise
+#: inside the bridge's child ("Playwright Sync API inside the asyncio loop"),
+#: so every JS-capable command fails without it.
+CAMOFOX_ENV_VAR = "CSE_CAMOFOX_URL"
+
+#: Default loopback Camofox endpoint used when the variable is unset.
+DEFAULT_CAMOFOX_URL = "http://127.0.0.1:9377"
+
+#: Values of ``SUD_CLI_BRIDGE_LIVE`` that count as enabled. Kept in step with
+#: ``case_search_bridge._live_access_enabled`` — an unset variable must never
+#: open network access.
+LIVE_ENABLED_VALUES = frozenset({"1", "true", "yes", "on"})
+
+#: Real court references, covering each prefix shape the bridge accepts.
+#: Prefixes are mixed alphanumerics of up to 4 characters and letters are legal
+#: in ANY position — ГАС Правосудие prints ``2а-2939/2025`` with a digit first.
+#: These are examples for the agent, not a validation contract: the pattern
+#: itself lives in ``case_search_bridge`` and is exercised by its own tests.
+CASE_REFERENCE_EXAMPLES = (
+    ("А40-11111/25", "АС Москвы — the abbreviated two-digit year courts print"),
+    ("А40-11111/2025", "same case, four-digit year"),
+    ("33-35073/2026", "SudRF, no letter prefix"),
+    ("2а-2939/2025", "ГАС Правосудие — district court, digit before letter"),
+    ("16АП-12345/2025", "appellate instance, letter suffix"),
+)
+
+#: Commands that reach an external court host through the bridge.
+LIVE_COMMANDS = (
+    "lookup",
+    "case-history",
+    "sudrf-live",
+    "mos-live",
+    "search-practice",
+    "kad-search",
+    "get-text",
+)
+
+
+def _entry(ok: bool, detail: str, remedy: str = "") -> Dict[str, Any]:
+    entry: Dict[str, Any] = {"ok": ok, "detail": detail}
+    if remedy:
+        entry["remedy"] = remedy
+    return entry
+
+
+def _live_flag_enabled(environ: Dict[str, str]) -> bool:
+    return str(environ.get(LIVE_ENV_VAR, "")).strip().lower() in LIVE_ENABLED_VALUES
+
+
+def _check_live_flag(environ: Dict[str, str]) -> Dict[str, Any]:
+    raw = environ.get(LIVE_ENV_VAR)
+    if raw is None:
+        return _entry(
+            False,
+            f"{LIVE_ENV_VAR} is not set; all court commands return 'blocked'",
+            f"export {LIVE_ENV_VAR}=1",
+        )
+    if _live_flag_enabled(environ):
+        return _entry(True, f"{LIVE_ENV_VAR}={raw} enables live court access")
+    return _entry(
+        False,
+        f"{LIVE_ENV_VAR}={raw!r} is not an enabling value",
+        f"export {LIVE_ENV_VAR}=1",
+    )
+
+
+def _check_binary(environ: Dict[str, str]) -> Dict[str, Any]:
+    path = environ.get("PATH", "")
+    # An explicitly empty PATH must read as "not installed", not as "fall back
+    # to os.defpath": shutil.which(cmd, path=None) searches the default PATH
+    # and would report a binary the caller cannot actually reach.
+    found = shutil.which("case-search", path=path) if path else None
+    if not found:
+        return _entry(
+            False,
+            "case-search is not on PATH",
+            "install case-search v1.2.0 or add it to PATH",
+        )
+    return _entry(True, f"case-search found at {found}")
+
+
+def _check_license(environ: Dict[str, str]) -> Dict[str, Any]:
+    explicit = environ.get("CSE_LICENSE_FILE")
+    candidates = (
+        [explicit]
+        if explicit
+        else [
+            str(Path(environ.get("HOME", str(Path.home()))) / ".config" / "case-search" / "config.json")
+        ]
+    )
+    for candidate in candidates:
+        if candidate and Path(candidate).expanduser().is_file():
+            return _entry(True, f"license file present at {candidate}")
+    return _entry(
+        False,
+        "no case-search license file; licensed commands fail with rc=4",
+        "set CSE_LICENSE_FILE or install ~/.config/case-search/config.json",
+    )
+
+
+def _camofox_url(environ: Dict[str, str]) -> Optional[str]:
+    raw = environ.get(CAMOFOX_ENV_VAR)
+    return raw.strip() if raw and raw.strip() else None
+
+
+def _probe_camofox(url: str, timeout: float = 4.0) -> Optional[bool]:
+    """Return True/False if the runtime answered, None if it did not respond.
+
+    Any HTTP answer counts as up: the endpoint is a local service whose job is
+    to render pages, and its status body is not the question being asked here.
+    """
+    try:
+        with urlopen(url.rstrip("/") + "/health", timeout=timeout) as resp:
+            resp.read(1024)
+            return True
+    except URLError:
+        # A 4xx/5xx still proves the listener is there.
+        return False
+    except Exception:
+        return None
+
+
+def _check_camofox(environ: Dict[str, str]) -> Dict[str, Any]:
+    configured = _camofox_url(environ)
+    if not configured:
+        return _entry(
+            False,
+            f"{CAMOFOX_ENV_VAR} is not set; JS-capable commands fall back to the "
+            "in-process browser and fail",
+            f"export {CAMOFOX_ENV_VAR}={DEFAULT_CAMOFOX_URL}",
+        )
+    answer = _probe_camofox(configured)
+    if answer is True:
+        return _entry(True, f"camofox runtime reachable at {configured}")
+    if answer is False:
+        return _entry(
+            False,
+            f"camofox runtime at {configured} answered with an error status",
+            "start it, then re-run this check",
+        )
+    return _entry(
+        False,
+        f"camofox runtime at {configured} did not answer",
+        "start it, then re-run this check",
+    )
+
+
+def _check_legal_rules() -> Dict[str, Any]:
+    """Report the tariff ruleset the engine will actually apply.
+
+    Reading it here proves the engine is usable before an agent spends a
+    calculation on it, and pins the exact spec/tariff versions that produced a
+    number — a fee computed under 1.0.0 is not the same claim as one under 1.1.0.
+    """
+    from sud_cli.legal_engine import load_rules
+
+    rules = load_rules()
+    if not isinstance(rules, dict):
+        return _entry(False, "legal rules file did not parse into a mapping")
+    spec = rules.get("spec_version") or rules.get("version") or "unknown"
+    tariff = rules.get("tariff_version", "unknown")
+    calendar = rules.get("production_calendar") or {}
+    transfers = calendar.get("government_transfers_encoded_through", "n/a")
+    status = calendar.get("status", "unknown")
+    return _entry(
+        True,
+        f"legal rules spec v{spec} (tariff {tariff}); production calendar "
+        f"{status}, government transfers encoded through {transfers}",
+    )
+
+
+def check_live_readiness(environ: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+    """Return a machine-readable readiness report.
+
+    ``ready`` is true only when every blocking check passed. It is a statement
+    about configuration, never about whether a given court answers — the tool
+    cannot know that without making a request.
+    """
+    source: Dict[str, str] = dict(environ if environ is not None else os.environ)
+
+    named_checks = {
+        "live_access": _check_live_flag(source),
+        "case_search_binary": _check_binary(source),
+        "license": _check_license(source),
+        "camofox_runtime": _check_camofox(source),
+        "legal_rules": _check_legal_rules(),
+    }
+    blocking = [name for name, check in named_checks.items() if not check["ok"]]
+    return {
+        "ready": not blocking,
+        "checks": named_checks,
+        "blocked_by": blocking,
+        "usage": {
+            "case_reference_examples": [
+                {"reference": ref, "note": note} for ref, note in CASE_REFERENCE_EXAMPLES
+            ],
+            "lookup_note": (
+                "lookup defaults to case-search's 'synthetic' provider, which "
+                "only knows fixture ids — always pass --source kad|mos-gorsud|"
+                "mos-gorsud-dom|sudrf"
+            ),
+            "live_commands": list(LIVE_COMMANDS),
+            "global_flags": ["--json must precede the subcommand", "--version"],
+        },
+    }

sud_cli/regional_holidays.py

@@ -0,0 +1,37 @@
+"""Fixed regional non-working holidays used as an optional calendar layer."""
+
+from datetime import date
+
+REGIONS = {
+    "02": {"name": "Республика Башкортостан", "holidays": {"03-17": "День Конституции", "10-11": "День Республики"}},
+    "03": {"name": "Республика Бурятия", "holidays": {"07-11": "День Республики"}},
+    "05": {"name": "Республика Дагестан", "holidays": {"09-15": "День единства народов Дагестана"}},
+    "14": {"name": "Республика Саха (Якутия)", "holidays": {"04-27": "День Республики"}},
+    "16": {"name": "Республика Татарстан", "holidays": {"08-30": "День Республики Татарстан", "11-06": "День Конституции Татарстана"}},
+    "20": {"name": "Чеченская Республика", "holidays": {"09-06": "День гражданского согласия и единения"}},
+    "91": {"name": "Республика Крым", "holidays": {"03-18": "День воссоединения с Россией", "09-20": "День Республики Крым"}},
+    "77": {"name": "Федеральный календарь", "holidays": {}},
+}
+
+
+def normalize_region(region):
+    if region is None:
+        return None
+    code = str(region).strip()
+    if code == "9":
+        code = "09"
+    if code not in REGIONS:
+        raise ValueError(f"unknown region code: {region}")
+    return code
+
+
+def holidays_for_year(year, region=None):
+    code = normalize_region(region)
+    if code is None or code == "77":
+        return set()
+    return {date(year, int(token[:2]), int(token[3:])) for token in REGIONS[code]["holidays"]}
+
+
+def region_name(region):
+    code = normalize_region(region)
+    return REGIONS[code]["name"] if code else None

sud_cli/reminders.py

@@ -0,0 +1,92 @@
+"""the wave §2 (S-26): reminders due — bus-free генератор готовых a2a-строк.
+
+Границы:
+- sud-cli НИКОГДА не вызывает шину a2a сам: модуль не импортирует ничего,
+  что умеет запускать внешние процессы. Здесь только чистые функции над
+  списком состояний сроков и сборка строки-текста. Исполняет строку
+  оператор или агент-планировщик осознанно, вне sud.
+- Источник данных — deadline_states (the wave): state computed|confirmed,
+  due_at ISO; due_at NULL и waived пропускаются молча, но не угадываются.
+- числа в теле письма есть => по политике a2a строка обязана нести
+  --verify "<детерминированная команда>" --verify-run.
+"""
+from datetime import date, timedelta
+from typing import List
+
+DUE_STATES = ("computed", "confirmed")
+
+BUS_FREE_NOTE = (
+    "bus-free: sud-cli не вызывает a2a; ниже готовые экранированные строки "
+    "команд — исполнение остаётся за оператором"
+)
+
+VERIFY_CMD_TEMPLATE = "/usr/bin/sud-cli reminders due --days {days} --json"
+
+
+def _latest_per_key(states):
+    """Последнее состояние на пару (case_id, deadline_key): id растёт с историей."""
+    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 list(latest.values())
+
+
+def due_items(states, today, days: int) -> List[dict]:
+    """Сроки, попадающие в окно [today, today+days], по последнему состоянию."""
+    horizon = today + timedelta(days=days)
+    items = []
+    for s in _latest_per_key(states):
+        if s.get("state") not in DUE_STATES:
+            continue
+        due_raw = s.get("due_at")
+        if not due_raw:
+            continue
+        try:
+            due = date.fromisoformat(str(due_raw)[:10])
+        except ValueError:
+            continue
+        if not (today <= due <= horizon):
+            continue
+        items.append({
+            "case_id": s.get("case_id"),
+            "deadline_key": s.get("deadline_key"),
+            "due_at": due.isoformat(),
+            "days_left": (due - today).days,
+            "state": s.get("state"),
+        })
+    items.sort(key=lambda i: (i["due_at"], str(i["case_id"]), str(i["deadline_key"])))
+    return items
+
+
+def a2a_command(item, days: int) -> str:
+    """Одна готовая строка a2a mail send; все значения экранированы shlex."""
+    import shlex
+    subject = f"deadline: {item['case_id']}/{item['deadline_key']} до {item['due_at']}"
+    body = (
+        f"Напоминание: срок {item['deadline_key']} по делу {item['case_id']} "
+        f"до {item['due_at']}, осталось {item['days_left']} дн. "
+        f"Окно выборки: {days} дн. Сверка матрицы: sud-cli deadlines list {item['case_id']}. "
+        f"Срок может быть просрочен к дате исполнения — проверь до отправки."
+    )
+    verify = VERIFY_CMD_TEMPLATE.format(days=days)
+    parts = [
+        "a2a", "mail", "send",
+        "--to", "colleague-legal",
+        "--priority", "today",
+        "--subject", subject,
+        "--body", body,
+        "--verify", verify,
+        "--verify-run",
+    ]
+    return " ".join(shlex.quote(p) for p in parts)
+
+
+def generate_mail_commands(items, days: int) -> List[str]:
+    return [a2a_command(i, days) for i in items]