zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/doctor.py

@@ -0,0 +1,535 @@
+"""zeno doctor - diagnostic suite for the local install.
+
+One-shot health check the operator runs when something feels off. Each row
+is a single check that prints a colored status (PASS/WARN/FAIL) + a detail
+string. Exit code: 0 if every row is PASS, 1 if any row is FAIL. WARN rows
+do NOT fail the run - they're "look here next" hints.
+
+Checks (in execution order):
+  1. Python version (PASS >=3.12, FAIL <3.12)
+  2. zeno-cli package version (PASS if version_string() resolves)
+  3. Local SQLite DB exists at ~/.zeno/zeno.db
+  4. Last survey timestamp (WARN if >7 days, PASS otherwise, WARN if absent)
+  5. API reachability via GET /v1/health (WARN if unreachable; zeno is local-first)
+  6. Tailnet identity via GET /v1/me (PASS if identity comes back, WARN otherwise)
+  7. Cognitive-state cache freshness at ~/.zeno/cognitive-state.json (WARN if absent/stale)
+  8. Capture hook installed (checks settings.json AND settings.local.json; WARN if absent)
+  9. Session-intel (ingest/usage) analytics surface importable (WARN if absent)
+ 10. Bunmail reachability (only when ZENO_BUNMAIL_BASE_URL set)
+
+The doctor is intentionally chatty (one row per check, not collapsed) so
+the operator can paste the output into a support thread or self-diagnose.
+Network checks default to a 2s timeout each so a doctor run finishes in
+under 10s even when everything is unreachable.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sqlite3
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .version import version_string
+
+# Status codes used by every row. Mirrors `zeno email check-dns`.
+STATUS_PASS = "PASS"
+STATUS_WARN = "WARN"
+STATUS_FAIL = "FAIL"
+
+# Timeout for every network probe (seconds). Total wall-time for a doctor
+# run with two unreachable hosts is bounded by NUM_NET_CHECKS * NET_TIMEOUT.
+NET_TIMEOUT = 2.0
+
+# Last-survey staleness threshold. Past this, doctor flags WARN; past 14
+# days it would arguably FAIL, but Mar's PM2 dogfood policy is "log every
+# coding session", and weekly-only counts as WARN-worthy not broken.
+SURVEY_STALE_DAYS = 7
+
+# Cognitive-state cache file lives next to the SQLite DB. Per research 2
+# the cache is touched on every /v1/cognitive-state read; older than 30
+# minutes means either the API is unreachable or no GET has happened in
+# a while - both worth flagging WARN.
+COGNITIVE_STATE_STALE_MINUTES = 30
+
+
+@dataclass(slots=True, frozen=True)
+class DoctorCheck:
+    """One row of the doctor output. label is the diagnostic name, status
+    is PASS/WARN/FAIL, detail is a short context string."""
+
+    label: str
+    status: str
+    detail: str
+
+
+def _http_get(
+    url: str, *, timeout: float, headers: dict[str, str] | None = None
+) -> tuple[int, str]:
+    """Best-effort GET. Returns (status_code, body) or (0, error_message) on failure.
+
+    A status_code of 0 is the sentinel for "couldn't even open the socket";
+    the caller treats it as FAIL. HTTP error responses (401/500/etc.) still
+    surface their code so the operator can see the failure mode.
+    """
+    request_headers = {"Accept": "application/json"}
+    if headers:
+        request_headers.update(headers)
+    request = Request(url=url, method="GET", headers=request_headers)
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            return response.status, response.read().decode("utf-8", errors="replace")
+    except HTTPError as exc:
+        try:
+            body = exc.read().decode("utf-8", errors="replace")
+        except (OSError, AttributeError):
+            body = str(exc.reason)
+        return exc.code, body
+    except (URLError, OSError) as exc:
+        return 0, str(exc)
+
+
+def check_python_version() -> DoctorCheck:
+    """Pass when Python >= 3.12, the minimum declared in apps/cli/pyproject.toml."""
+    major, minor = sys.version_info[:2]
+    label = "Python version"
+    detail = f"{major}.{minor}.{sys.version_info.micro}"
+    if (major, minor) >= (3, 12):
+        return DoctorCheck(label=label, status=STATUS_PASS, detail=detail)
+    return DoctorCheck(
+        label=label,
+        status=STATUS_FAIL,
+        detail=f"{detail} (requires 3.12+)",
+    )
+
+
+def check_zeno_version() -> DoctorCheck:
+    """Always passes when version_string() resolves to something printable.
+
+    The point of this row is to fingerprint the install in the doctor
+    output so support can answer "what version are you on" without a
+    follow-up question.
+    """
+    version = version_string()
+    return DoctorCheck(
+        label="zeno-cli version",
+        status=STATUS_PASS,
+        detail=version,
+    )
+
+
+def check_local_db(db_path: Path) -> DoctorCheck:
+    """SQLite DB lives at $ZENO_DB_PATH or ~/.zeno/zeno.db. Verify it exists
+    and is openable. A missing DB is WARN not FAIL - a brand-new install
+    that hasn't run `zeno survey` yet is a valid state.
+    """
+    label = "Local SQLite DB"
+    if not db_path.exists():
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail=f"{db_path} (run 'zeno survey' to create)",
+        )
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            # Read sqlite_master, not `SELECT 1`. `SELECT 1` is a constant that
+            # never touches the file, so a corrupt / non-sqlite file slips
+            # through - and inconsistently across sqlite builds (it raised on
+            # macOS sqlite but PASSed on the CI runner's sqlite). Reading the
+            # schema forces a page-1/header read, which raises SQLITE_NOTADB on
+            # a genuinely bad file uniformly.
+            conn.execute("SELECT count(*) FROM sqlite_master").fetchone()
+        finally:
+            conn.close()
+    except sqlite3.Error as exc:
+        return DoctorCheck(label=label, status=STATUS_FAIL, detail=f"{db_path}: {exc}")
+    return DoctorCheck(label=label, status=STATUS_PASS, detail=str(db_path))
+
+
+def check_last_survey(db_path: Path) -> DoctorCheck:
+    """Read the most recent load_probes.responded_at and rate its staleness.
+
+    No DB / no probes -> WARN with the bootstrap hint. Today -> PASS.
+    1-7 days -> PASS with a soft hint. >7 days -> WARN (the streak is
+    probably broken too; doctor surfaces this so the next action is
+    obvious).
+    """
+    label = "Last survey"
+    if not db_path.exists():
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail="no DB yet (run 'zeno survey')",
+        )
+    try:
+        conn = sqlite3.connect(str(db_path))
+        try:
+            row = conn.execute(
+                "SELECT MAX(responded_at) FROM load_probes WHERE responded_at IS NOT NULL"
+            ).fetchone()
+        finally:
+            conn.close()
+    except sqlite3.Error as exc:
+        return DoctorCheck(label=label, status=STATUS_WARN, detail=f"query failed: {exc}")
+
+    if row is None or row[0] is None:
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail="no surveys yet (run 'zeno survey')",
+        )
+
+    try:
+        ts = datetime.fromisoformat(str(row[0]))
+    except ValueError:
+        return DoctorCheck(label=label, status=STATUS_WARN, detail=f"unparseable: {row[0]!r}")
+
+    now = datetime.now(ts.tzinfo) if ts.tzinfo else datetime.now()
+    delta = now - ts
+    iso = ts.isoformat(timespec="seconds")
+    if delta < timedelta(days=1):
+        return DoctorCheck(label=label, status=STATUS_PASS, detail=f"today ({iso})")
+    if delta <= timedelta(days=SURVEY_STALE_DAYS):
+        return DoctorCheck(
+            label=label,
+            status=STATUS_PASS,
+            detail=f"{delta.days}d ago ({iso})",
+        )
+    return DoctorCheck(
+        label=label,
+        status=STATUS_WARN,
+        detail=f"{delta.days}d ago ({iso}) - run 'zeno survey'",
+    )
+
+
+def check_capture_hook(settings_path: Path | None = None) -> DoctorCheck:
+    """Is the zeno capture hook wired into Claude Code's settings.json?
+
+    A CLI install with no ``zeno hook install`` captures ZERO sessions, yet every
+    other row still PASSes - so doctor surfaces it. WARN, not FAIL: capture is opt-in
+    (some users only want the CLI), so a missing hook should not fail the run.
+
+    Presence uses the same dual-file resolution rule as the HUD installer's own
+    presence check (``hud.hud_install.capture_hook_present``) - an independent read here,
+    not a shared call, so keep the two in sync by hand: when no explicit path is given,
+    BOTH ``settings.json`` AND its sibling ``settings.local.json`` are consulted.
+    That dual lookup matters on a symlinked-dotfiles machine (Mar's own setup): when
+    ``settings.json`` is a symlink into a shared dotfiles checkout, ``zeno hud install``
+    redirects the write to the host-local ``settings.local.json``, so reading only
+    ``settings.json`` here FALSE-WARNed "not installed" even when capture was live.
+
+    An explicit ``settings_path`` is honored verbatim (single file) - that's the contract
+    the CLI's ``--settings-path`` and the test suite rely on; the settings.local.json
+    fallback only kicks in for the default (``settings_path is None``) path.
+    """
+    from .hook_install import HOOK_EVENTS, default_settings_path, status  # noqa: PLC0415
+
+    label = "Capture hook"
+    n = len(HOOK_EVENTS)
+
+    if settings_path is not None:
+        candidates: list[Path] = [settings_path]
+    else:
+        base = default_settings_path()
+        candidates = [base, base.with_name("settings.local.json")]
+
+    # Read every candidate; keep the status with the MOST installed events (so a hook in
+    # settings.local.json wins over an empty/symlinked settings.json). `read_ok` tracks
+    # whether any candidate was readable at all, to distinguish "not installed" from
+    # "could not read".
+    best = None
+    read_ok = False
+    for candidate in candidates:
+        try:
+            cand_st = status(candidate)
+        except Exception:
+            continue
+        read_ok = True
+        if best is None or len(cand_st["events_installed"]) > len(best["events_installed"]):
+            best = cand_st
+
+    if not read_ok or best is None:
+        return DoctorCheck(
+            label=label, status=STATUS_WARN, detail=f"could not read {candidates[0]}"
+        )
+    if best["all_events_installed"]:
+        return DoctorCheck(label=label, status=STATUS_PASS, detail=f"installed ({n} events)")
+    if best["events_installed"]:
+        got = len(best["events_installed"])
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail=f"partial ({got}/{n} events); re-run 'zeno hook install'",
+        )
+    return DoctorCheck(
+        label=label,
+        status=STATUS_WARN,
+        detail="not installed - run 'zeno hook install' to capture sessions",
+    )
+
+
+def check_api_health(base_url: str) -> DoctorCheck:
+    """GET /v1/health on the configured API base URL.
+
+    PASS on 200. Anything else is WARN, never FAIL: zeno is local-first, so an
+    unreachable API (an off-tailnet teammate) or a flaky server does not break
+    local capture + survey + curve. Only broken local dependencies (Python, the CLI,
+    the SQLite DB) FAIL on an end-user install, so a fresh local-only install is green.
+    (A repo checkout adds a dev-only ``Codegen`` row that FAILs on UNCOMMITTED generated
+    code - a real dev error, not a runtime dependency; it never exists on a wheel install.)
+    """
+    label = "API reachability"
+    url = f"{base_url.rstrip('/')}/v1/health"
+    code, body = _http_get(url, timeout=NET_TIMEOUT)
+    if code == 200:
+        return DoctorCheck(label=label, status=STATUS_PASS, detail=f"200 {url}")
+    if code == 0:
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail=f"unreachable - local-only mode (not on the tailnet?): {body[:50]}",
+        )
+    return DoctorCheck(label=label, status=STATUS_WARN, detail=f"{code} {url}")
+
+
+def check_tailnet_identity(base_url: str) -> DoctorCheck:
+    """GET /v1/me. PASS if a tier is returned. WARN if 401 (no identity yet),
+    WARN if API unreachable (the previous check already FAILed that).
+    """
+    label = "Tailnet identity"
+    # Centralized resolution: ZENO_API_TOKEN override, else the `zeno login`
+    # keyring token. Lazy import avoids a circular dependency (main imports
+    # doctor at module load).
+    from .main import resolve_api_token  # noqa: PLC0415
+
+    token = resolve_api_token()
+    headers = {"Authorization": f"Bearer {token}"} if token else None
+    url = f"{base_url.rstrip('/')}/v1/me"
+    code, body = _http_get(url, timeout=NET_TIMEOUT, headers=headers)
+    if code == 200:
+        try:
+            import json  # noqa: PLC0415
+
+            parsed = json.loads(body)
+            user = parsed.get("user_id", "<no user_id>")
+            tier = parsed.get("tier", "<no tier>")
+            return DoctorCheck(label=label, status=STATUS_PASS, detail=f"{user} tier={tier}")
+        except (ValueError, AttributeError):
+            return DoctorCheck(
+                label=label, status=STATUS_WARN, detail=f"200 but malformed: {body[:60]}"
+            )
+    if code == 401:
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail="401 (tailnet identity not present; ok for non-tailnet callers)",
+        )
+    if code == 0:
+        return DoctorCheck(label=label, status=STATUS_WARN, detail="skipped (API unreachable)")
+    return DoctorCheck(label=label, status=STATUS_WARN, detail=f"{code}: {body[:60]}")
+
+
+def check_cognitive_state_cache(cache_path: Path) -> DoctorCheck:
+    """~/.zeno/cognitive-state.json is the shared-memory cache from research 2.
+
+    Phase 0 contract: the API rewrites this file on every authed
+    /v1/cognitive-state read for the local operator. Doctor flags WARN
+    when the file is missing (Phase 0 not wired yet for this user) or
+    when the mtime is older than COGNITIVE_STATE_STALE_MINUTES (no recent
+    GET, so the gate is operating on stale info).
+    """
+    label = "Cognitive-state cache"
+    if not cache_path.exists():
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail=f"{cache_path} not present (call GET /v1/cognitive-state to populate)",
+        )
+    try:
+        mtime = datetime.fromtimestamp(cache_path.stat().st_mtime)
+    except OSError as exc:
+        return DoctorCheck(label=label, status=STATUS_WARN, detail=f"stat failed: {exc}")
+    age = datetime.now() - mtime
+    minutes = int(age.total_seconds() // 60)
+    if age > timedelta(minutes=COGNITIVE_STATE_STALE_MINUTES):
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail=f"stale ({minutes}m old)",
+        )
+    return DoctorCheck(
+        label=label,
+        status=STATUS_PASS,
+        detail=f"fresh ({minutes}m old)",
+    )
+
+
+def check_bunmail() -> DoctorCheck | None:
+    """Only runs when ZENO_BUNMAIL_BASE_URL is set. Returns None when env is
+    absent so doctor doesn't print a misleading "bunmail FAIL" row to
+    operators who don't use the outreach surface.
+
+    Bunmail's health endpoint is /health (no /v1 prefix - see bunmail repo).
+    Treating 200 as PASS and anything else as WARN; a flaky bunmail does
+    NOT break the rest of zeno.
+    """
+    base = os.environ.get("ZENO_BUNMAIL_BASE_URL", "").strip()
+    if not base:
+        return None
+    label = "Bunmail reachability"
+    url = f"{base.rstrip('/')}/health"
+    code, body = _http_get(url, timeout=NET_TIMEOUT)
+    if code == 200:
+        return DoctorCheck(label=label, status=STATUS_PASS, detail=f"200 {url}")
+    if code == 0:
+        return DoctorCheck(label=label, status=STATUS_WARN, detail=f"unreachable: {body}")
+    return DoctorCheck(label=label, status=STATUS_WARN, detail=f"{code} {url}")
+
+
+def _find_workspace_root() -> Path | None:
+    """Nearest ancestor of this file that is a zeno workspace checkout.
+
+    Identified by a `.git` dir + the `tools/codegen` tree. Returns None for a
+    wheel install in site-packages (no repo nearby) so the dev row is omitted
+    for end users, mirroring how check_bunmail is conditional.
+    """
+    here = Path(__file__).resolve()
+    for parent in [here.parent, *here.parents][:10]:
+        if (parent / ".git").exists() and (parent / "tools" / "codegen").is_dir():
+            return parent
+    return None
+
+
+def check_codegen_drift() -> DoctorCheck | None:
+    """Dev-only: are the codegen tools present and the generated SDK committed?
+
+    Returns None outside a workspace checkout. In a workspace:
+      - FAIL if uv or pnpm is missing (you cannot run `pnpm codegen`).
+      - FAIL if the generated SDK tree (sdk-python _generated + types) has
+        uncommitted changes - a regenerate that was not committed, or a
+        hand-edit of a generated file - with a remediation hint.
+      - PASS otherwise (tools present, generated tree clean). This is a fast,
+        read-only proxy; it does NOT run codegen (too heavy for a doctor run),
+        so the detail points at `pnpm codegen` for the authoritative check.
+    """
+    root = _find_workspace_root()
+    if root is None:
+        return None
+    label = "Codegen (dev)"
+
+    missing = [t for t in ("uv", "pnpm") if shutil.which(t) is None]
+    if missing:
+        # WARN not FAIL: a missing BUILD tool is not a broken runtime/local dependency,
+        # so it must not turn an otherwise-working checkout red (doctor_exit_code contract).
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail=f"{', '.join(missing)} not on PATH - skipping the codegen drift check",
+        )
+
+    gen_paths = [
+        "packages/sdk-python/src/zeno_sdk/_generated",
+        "packages/sdk-python/src/zeno_sdk/types",
+    ]
+    try:
+        out = subprocess.run(
+            ["git", "status", "--porcelain", "--", *gen_paths],
+            capture_output=True,
+            text=True,
+            timeout=3,
+            cwd=str(root),
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return DoctorCheck(label=label, status=STATUS_WARN, detail=f"git status failed: {exc}")
+
+    dirty = [ln for ln in out.stdout.splitlines() if ln.strip()]
+    if dirty:
+        return DoctorCheck(
+            label=label,
+            status=STATUS_FAIL,
+            detail=(
+                f"{len(dirty)} generated SDK file(s) uncommitted - run 'pnpm codegen' "
+                "and commit, or 'git restore' them"
+            ),
+        )
+    return DoctorCheck(
+        label=label,
+        status=STATUS_PASS,
+        detail="uv+pnpm present, generated SDK committed (run 'pnpm codegen' to re-verify)",
+    )
+
+
+def check_session_intel() -> DoctorCheck:
+    """Is the session-intel (ingest / usage) analytics surface importable?
+
+    ``zeno ingest`` / ``zeno usage`` fold the standalone ``zeno_session_intel`` sub-CLIs
+    (ingest + analytics) under the main CLI. That package is a workspace package, NOT
+    bundled into the zeno-cli wheel, so a bare wheel install lacks it and those two
+    commands print a hint instead of running. WARN, not FAIL, when absent: it is an
+    additive analytics surface, not a hard runtime dependency (doctor_exit_code
+    contract), so its absence must never turn an otherwise-healthy install red. This row
+    fingerprints whether the surface is wired so the operator isn't surprised by a hint.
+    """
+    import importlib  # noqa: PLC0415
+
+    label = "Session-intel (ingest/usage)"
+    try:
+        importlib.import_module("zeno_session_intel.ingest")
+        importlib.import_module("zeno_session_intel.analytics")
+    except ImportError:
+        return DoctorCheck(
+            label=label,
+            status=STATUS_WARN,
+            detail="not importable - 'zeno ingest'/'zeno usage' need the "
+            "zeno-session-intel package (run from the workspace or install it)",
+        )
+    return DoctorCheck(
+        label=label,
+        status=STATUS_PASS,
+        detail="importable ('zeno ingest' / 'zeno usage' available)",
+    )
+
+
+def run_doctor(
+    *, base_url: str, db_path: Path, cache_path: Path, settings_path: Path | None = None
+) -> list[DoctorCheck]:
+    """Execute every doctor check and return the list of DoctorCheck rows.
+
+    Pure-ish: each row is a function call; the rendering layer in main.py
+    handles colors and the exit code computation. Keeping this list-of-rows
+    shape makes the doctor easy to unit-test (no terminal mocking) and
+    easy to extend (append a new check).
+    """
+    checks: list[DoctorCheck] = [
+        check_python_version(),
+        check_zeno_version(),
+        check_local_db(db_path),
+        check_last_survey(db_path),
+        check_capture_hook(settings_path),
+        check_session_intel(),
+        check_api_health(base_url),
+        check_tailnet_identity(base_url),
+        check_cognitive_state_cache(cache_path),
+    ]
+    bunmail = check_bunmail()
+    if bunmail is not None:
+        checks.append(bunmail)
+    codegen = check_codegen_drift()
+    if codegen is not None:
+        checks.append(codegen)
+    return checks
+
+
+def doctor_exit_code(checks: list[DoctorCheck]) -> int:
+    """0 if every row is PASS or WARN, 1 if any row is FAIL. WARN does not
+    fail the run - that's the explicit contract documented at the top of
+    this file. A FAIL row means a hard dependency is broken.
+    """
+    return 1 if any(c.status == STATUS_FAIL for c in checks) else 0