ghost-api-cli 0.2.0__py3-none-any.whl

ghost_api/drift.py

@@ -0,0 +1,344 @@
+"""API drift: what changed in a site's API, how much it matters, and the client's version.
+
+A *snapshot* is what a client user sees: each method (its call, parameters and return
+type) and each model (its fields and their types). Snapshots are stored per site with a
+version number. Comparing two snapshots gives a list of changes:
+
+    breaking   code using the client can stop working: a method or field is gone, a type
+               changed, a parameter became required or disappeared
+    additive   something new: a method, an optional parameter, a field, a model
+
+The client's version follows semantic versioning: breaking -> major, additive -> minor,
+anything else (a description, an example) -> patch. The first version is 1.0.0.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import asdict, dataclass
+from typing import Any, Literal
+
+from ghost_api.generator.spec import ClientSpec
+from ghost_api.memory.store import Store
+
+Severity = Literal["breaking", "additive", "info"]
+FIRST_VERSION = "1.0.0"
+
+
+@dataclass(frozen=True)
+class Change:
+    severity: Severity
+    where: str  # "get_quotes", "Quote.author"
+    text: str  # plain words: "returns QuotesResponse instead of list[Quote]"
+    # "client": the client Ghost API generates now differs from the last version (the site's
+    # data changed, or a newer Ghost API types things differently); "live": a fresh reply
+    # from the site differs from what was captured.
+    source: str = "client"
+
+    def line(self) -> str:
+        mark = {"breaking": "!", "additive": "+", "info": "~"}[self.severity]
+        live = "[live] " if self.source == "live" else ""
+        return f"{mark} {live}{self.where}: {self.text}"
+
+
+def snapshot(spec: ClientSpec) -> dict[str, Any]:
+    """The client's public shape, as plain JSON (stable order, so equal APIs compare equal)."""
+    return {
+        "methods": {
+            m.name: {
+                "call": f"{m.http_method} {m.host or ''}{m.path}",
+                "params": {p.name: {"type": p.type, "required": p.required} for p in m.params},
+                "returns": m.response_type,
+                "summary": m.summary,
+            }
+            for m in sorted(spec.methods, key=lambda m: m.name)
+        },
+        "models": {
+            md.name: {f.name: {"type": f.type, "optional": f.optional} for f in md.fields}
+            for md in sorted(spec.models, key=lambda md: md.name)
+        },
+    }
+
+
+def compare(old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    changes: list[Change] = []
+    old_m, new_m = old.get("methods", {}), new.get("methods", {})
+    for name in sorted(old_m.keys() - new_m.keys()):
+        changes.append(Change("breaking", name, f"method removed ({old_m[name]['call']})"))
+    for name in sorted(new_m.keys() - old_m.keys()):
+        changes.append(Change("additive", name, f"new method ({new_m[name]['call']})"))
+    for name in sorted(old_m.keys() & new_m.keys()):
+        changes += _method_changes(name, old_m[name], new_m[name])
+    old_d, new_d = old.get("models", {}), new.get("models", {})
+    for name in sorted(old_d.keys() - new_d.keys()):
+        changes.append(Change("breaking", name, "model removed"))
+    for name in sorted(new_d.keys() - old_d.keys()):
+        changes.append(Change("additive", name, "new model"))
+    for name in sorted(old_d.keys() & new_d.keys()):
+        changes += _field_changes(name, old_d[name], new_d[name])
+    return changes
+
+
+def _method_changes(name: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    out: list[Change] = []
+    if old["call"] != new["call"]:
+        out.append(Change("info", name, f"now calls {new['call']} (was {old['call']})"))
+    if old["returns"] != new["returns"]:
+        out.append(
+            Change("breaking", name, f"returns {new['returns']} instead of {old['returns']}")
+        )
+    if old.get("summary") != new.get("summary"):
+        out.append(Change("info", name, "description changed"))
+    old_p, new_p = old["params"], new["params"]
+    for p in sorted(old_p.keys() - new_p.keys()):
+        out.append(Change("breaking", f"{name}({p})", "parameter removed"))
+    for p in sorted(new_p.keys() - old_p.keys()):
+        if new_p[p]["required"]:
+            out.append(Change("breaking", f"{name}({p})", "new required parameter"))
+        else:
+            out.append(Change("additive", f"{name}({p})", "new optional parameter"))
+    for p in sorted(old_p.keys() & new_p.keys()):
+        a, b = old_p[p], new_p[p]
+        if a["type"] != b["type"]:
+            text = f"type {b['type']} instead of {a['type']}"
+            out.append(Change("breaking", f"{name}({p})", text))
+        if not a["required"] and b["required"]:
+            out.append(Change("breaking", f"{name}({p})", "is now required"))
+        elif a["required"] and not b["required"]:
+            out.append(Change("additive", f"{name}({p})", "is now optional"))
+    return out
+
+
+def _field_changes(model: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
+    out: list[Change] = []
+    for f in sorted(old.keys() - new.keys()):
+        out.append(Change("breaking", f"{model}.{f}", "field removed"))
+    for f in sorted(new.keys() - old.keys()):
+        out.append(Change("additive", f"{model}.{f}", f"new field ({new[f]['type']})"))
+    for f in sorted(old.keys() & new.keys()):
+        a, b = old[f]["type"], new[f]["type"]
+        if a == b:
+            continue
+        where = f"{model}.{f}"
+        # Reply data: a field that can no longer be None is safe for code reading it;
+        # one that may now be None is not.
+        if _without_none(a) == _without_none(b):
+            if _nullable(a) and not _nullable(b):
+                out.append(Change("info", where, "is now always present"))
+            else:
+                out.append(Change("breaking", where, f"may now be missing ({b})"))
+        else:
+            out.append(Change("breaking", where, f"type {b} instead of {a}"))
+    return out
+
+
+def _nullable(type_text: str) -> bool:
+    return "None" in [part.strip() for part in type_text.split("|")]
+
+
+def _without_none(type_text: str) -> str:
+    return " | ".join(p.strip() for p in type_text.split("|") if p.strip() != "None")
+
+
+def bump(version: str, changes: list[Change]) -> str:
+    major, minor, patch = (int(x) for x in version.split("."))
+    if any(c.severity == "breaking" for c in changes):
+        return f"{major + 1}.0.0"
+    if any(c.severity == "additive" for c in changes):
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+@dataclass
+class VersionInfo:
+    version: str
+    changes: list[Change]
+    previous: str | None  # the version this one follows, None for the first
+    is_new: bool  # differs from the latest stored version
+    history: list[dict[str, Any]]  # stored versions, newest first (for changelogs)
+
+    def summary(self) -> str:
+        if self.previous is None:
+            return f"first version {self.version}"
+        if not self.is_new:
+            return f"no change since {self.version}"
+        counts = {s: sum(c.severity == s for c in self.changes) for s in ("breaking", "additive")}
+        parts = [f"{n} {s}" for s, n in counts.items() if n]
+        return f"{self.previous} -> {self.version} ({', '.join(parts) or 'small changes'})"
+
+
+def version_for(store: Store, domain: str, spec: ClientSpec) -> VersionInfo:
+    """The version `spec` has (or would get), compared with the latest stored one."""
+    history = store.api_versions(domain)
+    snap = snapshot(spec)
+    if not history:
+        return VersionInfo(FIRST_VERSION, [], None, True, history)
+    latest = history[0]
+    if latest["snapshot"] == snap:
+        return VersionInfo(latest["version"], [], latest["version"], False, history)
+    changes = compare(latest["snapshot"], snap)
+    return VersionInfo(bump(latest["version"], changes), changes, latest["version"], True, history)
+
+
+def record(store: Store, domain: str, spec: ClientSpec, run_id: int | None) -> VersionInfo:
+    """Store `spec` as a new version when it differs from the latest one."""
+    info = version_for(store, domain, spec)
+    if info.is_new:
+        store.add_api_version(
+            domain, info.version, snapshot(spec), [asdict(c) for c in info.changes], run_id
+        )
+    return info
+
+
+def changelog(spec: ClientSpec, info: VersionInfo) -> str:
+    """CHANGELOG.md for a client package: every stored version, plus this one if new."""
+    lines = [
+        f"# Changelog: {spec.class_name}",
+        "",
+        f"Versions of the unofficial {spec.domain} client, written by Ghost API when the "
+        "site's API changed. `!` breaking, `+` added, `~` other.",
+        "",
+    ]
+    entries = list(info.history)
+    if info.is_new:
+        entries.insert(
+            0,
+            {"version": info.version, "created_at": "unreleased",
+             "changes": [asdict(c) for c in info.changes]},
+        )  # fmt: skip
+    for entry in entries:
+        lines += [f"## {entry['version']} ({str(entry['created_at'])[:10]})", ""]
+        changes = [Change(**c) for c in entry["changes"]]
+        lines += [f"- {c.line()}" for c in changes] or ["- First version."]
+        lines.append("")
+    return "\n".join(lines)
+
+
+def to_markdown(site: str, info: VersionInfo, changes: list[Change]) -> str:
+    """A pull-request body for `ghost-api diff --markdown`."""
+    if not changes:
+        return f"No API changes for **{site}** (client {info.version})."
+    breaking = [c for c in changes if c.severity == "breaking"]
+    lines = [
+        f"## API changes on {site}",
+        "",
+        f"Client version **{info.previous or '-'} -> {info.version}**"
+        + (f": **{len(breaking)} breaking**" if breaking else ""),
+        "",
+    ]
+    for title, severity in (("Breaking", "breaking"), ("Added", "additive"), ("Other", "info")):
+        group = [c for c in changes if c.severity == severity]
+        if group:
+            lines += [f"### {title}", ""] + [f"- `{c.where}`: {c.text}" for c in group] + [""]
+    lines.append("Generated by [Ghost API](https://github.com/Danielraj5605/Ghost-api).")
+    return "\n".join(lines)
+
+
+def changes_json(changes: list[Change]) -> list[dict[str, Any]]:
+    return [asdict(c) for c in changes]
+
+
+def dumps(snap: dict[str, Any]) -> str:
+    return json.dumps(snap, sort_keys=True)
+
+
+# --- live check: compare a fresh reply with the stored response schema ---------------------
+
+
+@dataclass(frozen=True)
+class FieldShape:
+    types: frozenset[str]
+    required: bool  # present in every captured reply
+
+
+def schema_fields(schema: dict[str, Any] | None, max_depth: int = 4) -> dict[str, FieldShape]:
+    """{"quotes[].author.name": FieldShape({"string"}, True), ...} for a JSON schema."""
+    out: dict[str, FieldShape] = {}
+
+    def types(node: dict[str, Any]) -> frozenset[str]:
+        kind = node.get("type")
+        found = set(kind) if isinstance(kind, list) else {kind} if kind else set()
+        for option in node.get("anyOf", []):
+            found |= types(option)
+        return frozenset(t for t in found if t)
+
+    def walk(node: dict[str, Any], prefix: str, required: bool, depth: int) -> None:
+        kinds = types(node)
+        if prefix:
+            out[prefix] = FieldShape(kinds, required)
+        if depth >= max_depth:
+            return
+        if "array" in kinds and isinstance(node.get("items"), dict):
+            walk(node["items"], prefix + "[]", required, depth + 1)
+        needed = set(node.get("required", []))
+        for key, child in (node.get("properties") or {}).items():
+            if isinstance(child, dict):
+                path = f"{prefix}.{key}" if prefix else key
+                walk(child, path, required and key in needed, depth + 1)
+        for option in node.get("anyOf", []):
+            if isinstance(option, dict) and option.get("properties"):
+                walk({**option, "type": None}, prefix, required, depth)
+
+    if schema:
+        walk(schema, "", True, 0)
+    return out
+
+
+def live_changes(
+    where: str, stored: dict[str, Any] | None, fresh: dict[str, Any] | None
+) -> list[Change]:
+    """How a fresh reply differs from what was captured before. A field missing from one
+    reply is only breaking when every earlier reply had it."""
+    before, now = schema_fields(stored), schema_fields(fresh)
+    out: list[Change] = []
+    for path in sorted(before.keys() - now.keys()):
+        if before[path].required and "[]" not in path.rstrip("[]"):
+            out.append(
+                Change("breaking", f"{where} {path}", "field missing from the reply", "live")
+            )
+    for path in sorted(now.keys() - before.keys()):
+        out.append(Change("additive", f"{where} {path}", "new field in the reply", "live"))
+    for path in sorted(before.keys() & now.keys()):
+        old, new = before[path].types - {"null"}, now[path].types - {"null"}
+        if old and new and not (new <= old or {"integer", "number"} >= old | new):
+            text = f"now {'/'.join(sorted(new))}, was {'/'.join(sorted(old))}"
+            out.append(Change("breaking", f"{where} {path}", text, "live"))
+    return out
+
+
+def live_check(
+    store: Store, site: str, on_progress: Callable[[str], None] | None = None
+) -> list[Change]:
+    """Call each operation once (read-only, rate-limited, the site's rules apply) and
+    compare each reply's shape with what was captured."""
+    from ghost_api.analysis.schema import build_schema
+    from ghost_api.probe.replay import ReplayRefused
+    from ghost_api.runtime import OperationError, SiteRuntime
+
+    try:
+        runtime = SiteRuntime(store, site)
+    except OperationError as exc:
+        if on_progress is not None:
+            on_progress(f"live check skipped: {exc}")
+        return []
+    stored = {e.key: e.response_schema for e in store.current_endpoints(site)}
+    changes: list[Change] = []
+    with runtime:
+        for op in runtime.operations():
+            inputs = {i.name: i.example for i in op.inputs if i.example}
+            try:
+                result = runtime.call(op, inputs)
+            except (OperationError, ReplayRefused) as exc:
+                changes.append(Change("info", op.name, f"not checked live: {exc}", "live"))
+                continue
+            if not result.ok:
+                status = result.status or "network error"
+                changes.append(Change("breaking", op.name, f"live call failed ({status})", "live"))
+                continue
+            changes += live_changes(
+                op.name, stored.get(op.endpoint.key), build_schema([result.body])
+            )
+            if on_progress is not None:
+                on_progress(f"checked {op.name} live")
+    return changes

ghost_api/drive.py

@@ -0,0 +1,211 @@
+"""Explore a site one step at a time, with the decisions made elsewhere (an AI assistant).
+
+`ghost-api mcp --explore` hands these steps to Claude (or any MCP client): the assistant
+reads the page and decides; Ghost API acts with all its rules (robots.txt, rate limit,
+same site only, no destructive or login elements, no private network), records every
+request, and at the end tests the endpoints, writes the client, report and version, just
+like `ghost-api run`. No LLM key is needed: the assistant is the agent.
+
+Playwright's browser belongs to the thread that opened it, so each session runs all its
+work on one worker thread of its own.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any, TypeVar
+from urllib.parse import urlsplit
+
+from ghost_api.agent.orchestrator import BotProtection, Explorer
+from ghost_api.agent.prompts import format_page
+from ghost_api.agent.tools import Decision
+from ghost_api.analysis.analyzer import analyze
+from ghost_api.browser.driver import BrowserSession
+from ghost_api.config import check_language, default_db_path, load_env
+from ghost_api.events import EventBus
+from ghost_api.export.site_data import endpoint_summary
+from ghost_api.memory.knowledge import load_memory, memory_prompt
+from ghost_api.memory.store import Store
+from ghost_api.net import RateLimiter
+from ghost_api.pipeline import RunOptions, Session, finish, open_session, robots_policy
+from ghost_api.site import site_key
+from ghost_api.workflows import NotAllowed, RunCollector, enforce
+
+T = TypeVar("T")
+MAX_STEPS = 60  # a ceiling, so an assistant can't keep a browser busy forever
+
+
+class DriveError(Exception):
+    """Something the assistant should be told plainly (a closed session, a bad action)."""
+
+
+class DriveSession:
+    def __init__(
+        self,
+        url: str,
+        goal: str,
+        *,
+        db: Path | None = None,
+        out: Path = Path("output"),
+        lang: str = "python",
+        rate_limit: float = 1.0,
+        max_steps: int = MAX_STEPS,
+    ) -> None:
+        self.url, self.goal = url, goal
+        self.db = db or default_db_path()
+        self.out = out
+        self.lang = check_language(lang)
+        self.rate_limit = rate_limit
+        self.max_steps = max_steps
+        self.collector = RunCollector()
+        self.closed = False
+        self._worker = ThreadPoolExecutor(max_workers=1, thread_name_prefix="ghost-drive")
+        self._store: Store | None = None
+        self._session: Session | None = None
+        self._browser: BrowserSession | None = None
+        self._explorer: Explorer | None = None
+        self._started = 0.0
+
+    # --- public, thread-safe: every call runs on the session's own worker thread ---
+
+    def start(self) -> dict[str, Any]:
+        return self._run(self._start)
+
+    def page(self) -> str:
+        return self._run(self._page)
+
+    def act(self, action: str, **arguments: Any) -> dict[str, Any]:
+        return self._run(lambda: self._act(action, arguments))
+
+    def endpoints(self) -> list[dict[str, Any]]:
+        return self._run(self._endpoints)
+
+    def finish(self, goal_covered: bool = False, note: str = "") -> dict[str, Any]:
+        try:
+            return self._run(lambda: self._finish(goal_covered, note))
+        finally:
+            self._worker.shutdown(wait=False)
+
+    # --- the work ---
+
+    def _run(self, work: Callable[[], T]) -> T:
+        if self.closed:
+            raise DriveError("this exploration has finished; start a new one")
+        return self._worker.submit(work).result()
+
+    def _start(self) -> dict[str, Any]:
+        load_env()
+        host = urlsplit(self.url).hostname or ""
+        policy = enforce(site_key(self.url) or host, use_agent=True)  # the assistant decides
+        bus = EventBus()
+        bus.subscribe(self.collector)
+        limiter = RateLimiter(self.rate_limit)
+        robots, allowed = robots_policy(self.url, False, limiter, bus)
+        if not allowed:
+            raise NotAllowed(f"robots.txt does not allow {self.url}")
+        self._store = Store(self.db)
+        self._session = s = open_session(
+            self._store, bus, host, self.url, self.goal, False, limiter, robots, None,
+            min(60, policy.max_direct_calls or 60),
+            screens_root=self.db, lang=self.lang,
+        )  # fmt: skip
+        known = load_memory(self._store, s.site)
+        if known is not None:
+            s.memory = memory_prompt(known.endpoints, known.lessons)
+        self._browser = s.browser().__enter__()
+        self._explorer = Explorer(
+            self._browser, None, lambda: s.recorder.captured, self.goal, self.url, host,
+            robots=s.robots, on_step=s.on_step, replayer=s.replayer,
+            raw_requests=lambda: s.recorder.raw, add_sample=s.recorder.add, memory=s.memory,
+        )  # fmt: skip
+        self._started = time.monotonic()
+        self._explorer.begin()
+        return {
+            "site": s.site,
+            "memory": s.memory or "nothing known about this site yet",
+            "page": self._page(),
+            "endpoints": self._endpoints(),
+        }
+
+    def _require(self) -> tuple[Session, BrowserSession, Explorer]:
+        if self._session is None or self._browser is None or self._explorer is None:
+            raise DriveError("start the exploration first (open_site)")
+        return self._session, self._browser, self._explorer
+
+    def _page(self) -> str:
+        session, browser, _ = self._require()
+        return format_page(browser.snapshot(session.host, session.robots))
+
+    def _act(self, action: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        _, _, explorer = self._require()
+        if action in ("finish", "ask_user"):
+            raise DriveError(f"'{action}' is not a step here: use finish_exploration instead")
+        if len(explorer.steps) >= self.max_steps:
+            raise DriveError(f"step limit reached ({self.max_steps}); finish the exploration")
+        try:
+            decision = Decision(thought=str(arguments.pop("why", "") or "(assistant)"),
+                                action=action, **arguments)  # type: ignore[arg-type]  # fmt: skip
+        except ValueError as exc:
+            raise DriveError(f"not a valid {action}: {exc}") from exc
+        try:
+            record = explorer.act(decision)
+        except BotProtection as exc:
+            raise DriveError(
+                f"bot-protection page ({exc}): Ghost API never tries to get past it. Finish, "
+                "or record the site yourself and use `ghost-api import`."
+            ) from exc
+        return {
+            "result": record.result,
+            "new_endpoints": record.new_endpoints,
+            "page": self._page(),
+        }
+
+    def _endpoints(self) -> list[dict[str, Any]]:
+        session, _, _ = self._require()
+        found = analyze(session.recorder.captured)
+        return [_compact(endpoint_summary(e, session.site)) for e in found]
+
+    def _finish(self, goal_covered: bool, note: str) -> dict[str, Any]:
+        session, browser, explorer = self._require()
+        self.closed = True
+        try:
+            browser.__exit__(None, None, None)
+            covered = goal_covered and bool(analyze(session.recorder.captured))
+            status = "goal-covered" if covered else "finished"
+            reason = note or f"explored by an assistant in {len(explorer.steps)} step(s)"
+            opts = RunOptions(lang=self.lang, max_steps=self.max_steps, out=self.out)
+            finish(session, status, reason, self._started, opts)
+        finally:
+            if self._store is not None:
+                self._store.close()
+        data = self.collector.data
+        client = data.get("client") or {}
+        return {
+            "status": data.get("status"),
+            "site": data.get("site"),
+            "endpoints": [_compact(e) for e in data.get("endpoints", [])],
+            "client": {
+                "class": client.get("class_name"),
+                "directory": client.get("directory"),
+                "files": client.get("files", []),
+            }
+            if client
+            else None,
+            "report": data.get("report_html") or data.get("report"),
+            "openapi": data.get("openapi"),
+            "network": data.get("network"),
+        }
+
+
+def _compact(summary: dict[str, Any]) -> dict[str, Any]:
+    """What an assistant needs to decide, in few tokens: no schemas or examples."""
+    keep = ("method", "host", "path", "status", "statuses", "samples", "pagination",
+            "auth_type", "fields", "confidence")  # fmt: skip
+    out = {k: summary[k] for k in keep if summary.get(k) not in (None, [], {}, "")}
+    params = summary.get("params") or []
+    if params:
+        out["params"] = [f"{p['name']} ({p['location']})" for p in params][:12]
+    return out

ghost_api/errors.py

@@ -0,0 +1,106 @@
+"""Turn common low-level errors into plain explanations with a fix (NFR-23)."""
+
+from __future__ import annotations
+
+import re
+
+# (pattern in the error text, explanation and fix). The order matches ERROR_CODES.
+_KNOWN: list[tuple[re.Pattern[str], str]] = [
+    (
+        re.compile(r"Executable doesn't exist|playwright install", re.I),
+        "Chromium isn't installed for Playwright. Run: playwright install chromium",
+    ),
+    (
+        re.compile(r"ERR_NAME_NOT_RESOLVED|getaddrinfo failed|Name or service not known", re.I),
+        "The website's address could not be found. Check the URL and your internet connection.",
+    ),
+    (
+        re.compile(r"ERR_CONNECTION_REFUSED|Connection refused|actively refused", re.I),
+        "The website refused the connection. Is the URL (and port) right, and is the site up?",
+    ),
+    (
+        re.compile(r"ERR_UNSAFE_PORT", re.I),
+        "Browsers refuse to open this port for safety reasons. Use a different port.",
+    ),
+    (
+        re.compile(r"ERR_INTERNET_DISCONNECTED|ERR_NETWORK_CHANGED", re.I),
+        "No internet connection.",
+    ),
+    (
+        # Only the browser's own timeouts: an LLM or robots.txt timeout is not the website.
+        re.compile(r"Timeout \d+ms exceeded|net::ERR_(CONNECTION_)?TIMED_OUT", re.I),
+        "The website took too long to respond. Try again, or check that it loads in a browser.",
+    ),
+    (
+        re.compile(r"ERR_CERT_|CERTIFICATE_VERIFY_FAILED", re.I),
+        "The website's security certificate is not valid.",
+    ),
+    (
+        re.compile(r"file is not a database|database disk image is malformed", re.I),
+        "The database file is damaged or is not a Ghost API database. Move it aside "
+        "(or use --db to pick another file) and Ghost API will start a fresh one.",
+    ),
+    (
+        re.compile(r"database is locked", re.I),
+        "The database is busy, probably because another ghost-api command is running. "
+        "Wait for it to finish, or use --db to pick another file.",
+    ),
+]
+
+
+# Stable codes for the explanations above, in the same order: for logs, scripts and bug
+# reports, so nothing depends on the wording of a message.
+ERROR_CODES = (
+    "browser-missing",
+    "dns-failed",
+    "connection-refused",
+    "unsafe-port",
+    "offline",
+    "site-timeout",
+    "bad-certificate",
+    "database-damaged",
+    "database-locked",
+)
+
+
+def error_code(exc: BaseException) -> str:
+    """A stable short code for `exc` (see ERROR_CODES), 'network-denied',
+    'response-too-large', or 'unexpected'."""
+    from ghost_api.netguard import PolicyDenied, ResponseTooLarge
+
+    chain = _chain(exc)
+    if any(isinstance(e, PolicyDenied) for e in chain):
+        return "network-denied"
+    if any(isinstance(e, ResponseTooLarge) for e in chain):
+        return "response-too-large"
+    for error in chain:
+        for (pattern, _), code in zip(_KNOWN, ERROR_CODES, strict=True):
+            if pattern.search(str(error)):
+                return code
+    return "unexpected"
+
+
+def _chain(exc: BaseException) -> list[BaseException]:
+    chain = [exc]
+    while chain[-1].__cause__ is not None and len(chain) < 5:
+        chain.append(chain[-1].__cause__)
+    return chain
+
+
+def friendly_error(exc: BaseException) -> str:
+    """A short, human explanation of `exc`; falls back to its first line, plus the
+    underlying cause when there is one, so the real reason is not lost."""
+    for error in _chain(exc):
+        for pattern, message in _KNOWN:
+            if pattern.search(str(error)):
+                return message
+    text = _first_line(exc)
+    cause = exc.__cause__
+    if cause is not None and _first_line(cause) not in text:
+        text += f" (cause: {_first_line(cause)})"
+    return text[:300]
+
+
+def _first_line(exc: BaseException) -> str:
+    text = str(exc).strip()
+    return text.splitlines()[0] if text else type(exc).__name__