jpsync 1.0.0__py3-none-any.whl

jp/__init__.py

@@ -0,0 +1,23 @@
+"""jp -- a git-like CLI that safely syncs local folders with a remote JupyterHub.
+
+Stdlib-only, zero external dependencies. The package version is hard-coded as a
+reliable fallback and overridden by installed package metadata when available.
+"""
+
+from __future__ import annotations
+
+import contextlib
+
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"  # x-release-please-version
+
+try:  # Prefer the installed distribution's version when present.
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _version
+
+    with contextlib.suppress(PackageNotFoundError):
+        __version__ = _version("jpsync")
+    del _version, PackageNotFoundError
+except Exception:  # pragma: no cover - importlib.metadata always present on 3.8+
+    pass

jp/__main__.py

@@ -0,0 +1,10 @@
+"""Enable ``python -m jp``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

jp/api.py

@@ -0,0 +1,538 @@
+"""Thin JupyterHub / Jupyter-server Contents API client over stdlib urllib.
+
+Security rules (see docs/architecture.md):
+  * Authorization header ONLY -- the token is never put in the URL/query string.
+  * TLS is always verified (a real, default ``ssl`` context). We never disable
+    certificate checks.
+  * We refuse to send a token over plain ``http://`` (no cleartext credentials).
+  * Errors raised here are mapped to NetworkError/ApiError; the CLI passes their
+    messages through ``ui.redact`` so a token (and absolute server paths) can
+    never leak via an error.
+
+Empirical behaviour baked in (research/01-jupyter-api.md, JupyterHub 5.2.1):
+  * ``GET <file>?content=0&hash=1`` returns the **sha256** of the raw bytes
+    WITHOUT downloading the body (cheap even at 20 MiB). :meth:`hash` uses this
+    as the primary remote change-detection signal so we only download when the
+    remote hash differs from the local sha256.
+  * PUT auto-creates parent directories (``mkdir -p``); PATCH does NOT.
+  * PUT returns 201 (created) vs 200 (overwrote) -- surfaced as ``created``.
+  * ``GET`` 404 bodies are **plain text** (other errors are JSON) -> the error
+    parser is defensive and never raises while parsing.
+  * ``format=text`` does NOT reject binary; jp decides text-vs-binary itself.
+    Downloads always force ``type=file`` (byte-faithful, incl. ``.ipynb``) and
+    base64 ``content`` carries a trailing newline that must be stripped.
+  * Health probe: ``GET /api/status`` must NOT follow redirects; a 3xx to
+    ``/hub/...`` means the server is stopped (-> :class:`ServerDownError`).
+
+This module performs raw transport only; it does NOT enforce the path-jail and
+does NOT know the workspace prefix. The path-jail lives ENTIRELY in the callers
+(``sync.py`` / ``commands/rm.py``): they MUST call ``paths.remote_path_for`` to
+compose a remote path and ``paths.assert_within_prefix`` immediately before
+invoking any mutating method here (put/mkdir/rename/delete).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+from . import ui
+from .errors import ApiError, AuthError, NetworkError, ServerDownError
+
+_DEFAULT_TIMEOUT = 30.0
+
+# Warn (do not hard-fail) before loading a very large file fully into memory:
+# there is no chunking and base64 inflates payloads by ~33% (see docs/architecture.md).
+_LARGE_FILE_WARN_BYTES = 50 * 1024 * 1024  # ~50 MiB
+
+# Extensions we treat as opaque bytes even though the server reports them as a
+# "notebook" model. Forcing type=file keeps the bytes faithful (research §11).
+_NOTEBOOK_EXTS = (".ipynb",)
+
+
+@dataclass
+class RemoteEntry:
+    """One item from a Contents API directory listing."""
+
+    name: str
+    path: str
+    type: str  # "file" | "directory" | "notebook"
+    size: int | None
+    last_modified: str
+    mimetype: str | None = None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """A redirect handler that NEVER follows 3xx -- it re-raises the response.
+
+    We need this for the health probe: a stopped JupyterHub server answers
+    ``/api/status`` with a 302 into ``/hub/...``. urllib follows redirects by
+    default, which would hide that signal, so we install a dedicated opener that
+    surfaces the 3xx as an :class:`urllib.error.HTTPError` instead.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D401
+        return None  # do not build a follow-up request
+
+    def http_error_302(self, req, fp, code, msg, headers):
+        raise urllib.error.HTTPError(req.full_url, code, msg, headers, fp)
+
+    http_error_301 = http_error_303 = http_error_307 = http_error_308 = http_error_302
+
+
+@dataclass
+class StatusResult:
+    """Outcome of the health probe (see :meth:`Api.status_probe`)."""
+
+    up: bool
+    detail: str = ""
+
+
+def _is_notebook_path(api_path: str) -> bool:
+    name = api_path.rsplit("/", 1)[-1].lower()
+    return name.endswith(_NOTEBOOK_EXTS)
+
+
+def _looks_utf8_text(data: bytes) -> bool:
+    """True if ``data`` is safe to send as a UTF-8 ``format=text`` payload.
+
+    Embedded NULs or non-UTF-8 bytes mean we must use base64 instead -- the
+    server happily stores raw bytes in a text field (no 400), corrupting them.
+    """
+    if b"\x00" in data:
+        return False
+    try:
+        data.decode("utf-8")
+    except UnicodeDecodeError:
+        return False
+    return True
+
+
+class Api:
+    """Contents API client. One instance per repo/session."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: float = _DEFAULT_TIMEOUT,
+        ssl_context: ssl.SSLContext | None = None,
+        large_file_warn_bytes: int = _LARGE_FILE_WARN_BYTES,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._token = token
+        self.timeout = timeout
+        self.large_file_warn_bytes = large_file_warn_bytes
+        self._warned_large: set[str] = set()
+        # Always a verifying context. We never pass an unverified one.
+        self._ssl_context = ssl_context or ssl.create_default_context()
+        ui.register_secret(token)
+
+        scheme = urllib.parse.urlsplit(self.base_url).scheme
+        if scheme not in ("http", "https"):
+            raise NetworkError(f"unsupported base_url scheme: {scheme!r}")
+        if scheme == "http" and token:
+            # Never transmit credentials over cleartext.
+            raise AuthError("refusing to send a token over plain http:// -- use https://")
+
+    # --- low-level request --------------------------------------------------
+    def _url(self, api_path: str) -> str:
+        # Contents API lives under /user/<name>/api/contents OR /api/contents;
+        # base_url is expected to already include the api root. The token is
+        # NEVER appended here.
+        #
+        # CRITICAL: split off the query string FIRST. We percent-encode only the
+        # path segments (keeping '/' raw) and leave the query (?content=0&hash=1)
+        # verbatim -- otherwise '?', '=' and '&' get encoded too and the server
+        # treats the whole thing as a literal filename, silently ignoring every
+        # query parameter (content/hash/type/format).
+        raw = api_path.lstrip("/")
+        if "?" in raw:
+            path_part, query = raw.split("?", 1)
+            query = f"?{query}"
+        else:
+            path_part, query = raw, ""
+        quoted = urllib.parse.quote(path_part, safe="/")
+        return f"{self.base_url}/{quoted}{query}"
+
+    def _request(
+        self,
+        method: str,
+        api_path: str,
+        body: dict[str, Any] | None = None,
+    ) -> Any:
+        url = self._url(api_path)
+        data = None
+        headers = {
+            "Authorization": f"token {self._token}",
+            "Accept": "application/json",
+        }
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(
+                req, timeout=self.timeout, context=self._ssl_context
+            ) as resp:
+                payload = resp.read()
+                if not payload:
+                    return None
+                ctype = resp.headers.get("Content-Type", "")
+                if "json" in ctype or payload[:1] in (b"{", b"["):
+                    return json.loads(payload.decode("utf-8"))
+                return payload
+        except urllib.error.HTTPError as exc:
+            self._raise_for_http(exc)
+        except urllib.error.URLError as exc:
+            # Includes TLS verification failures and DNS/connection errors.
+            raise NetworkError(f"network error talking to server: {exc.reason}") from exc
+        except (TimeoutError, OSError) as exc:
+            raise NetworkError(f"network error: {exc}") from exc
+        return None
+
+    @staticmethod
+    def _error_detail(exc: urllib.error.HTTPError) -> str:
+        """Best-effort, never-raising extraction of a server error message.
+
+        404 bodies on this server are PLAIN TEXT; most other errors are JSON
+        ``{"message":...,"reason":...}``. We try JSON first, fall back to text,
+        and swallow everything so a malformed body cannot crash error handling.
+        Note: messages may leak an absolute ``/lapix/...`` path -- ``ui.redact``
+        masks those at the output boundary.
+        """
+        try:
+            raw = exc.read()
+        except Exception:
+            return ""
+        if not raw:
+            return ""
+        text = raw.decode("utf-8", "replace")
+        stripped = text.strip()
+        if stripped[:1] in ("{", "["):
+            try:
+                parsed = json.loads(stripped)
+            except ValueError:
+                return text[:200]
+            if isinstance(parsed, dict):
+                return str(parsed.get("message") or parsed.get("reason") or "")[:200]
+            return text[:200]
+        # Plain-text body (e.g. the 404 case).
+        return text[:200]
+
+    def _raise_for_http(self, exc: urllib.error.HTTPError) -> None:
+        status = exc.code
+        # Try to extract a server message, but never echo headers (which carry
+        # the Authorization we sent), and never raise while parsing.
+        detail = self._error_detail(exc)
+        msg = f"server returned HTTP {status}"
+        if detail:
+            msg += f": {detail}"
+        if status in (401, 403):
+            raise AuthError(msg)
+        raise ApiError(msg, status=status)
+
+    # --- read operations ----------------------------------------------------
+    def list_dir(self, api_path: str) -> list[RemoteEntry]:
+        """List a remote directory. Returns [] if it does not exist (404).
+
+        The listing carries only ``name/type/size/last_modified`` per child --
+        NO ``hash``/``content`` (research §1) -- so it is purely the cheap first
+        pass; per-file equality uses :meth:`hash`.
+        """
+        try:
+            data = self._request("GET", f"api/contents/{api_path}?content=1")
+        except ApiError as exc:
+            if exc.status == 404:
+                return []
+            raise
+        if not isinstance(data, dict):
+            return []
+        if data.get("type") != "directory":
+            return [self._to_entry(data)]
+        out: list[RemoteEntry] = []
+        for item in data.get("content") or []:
+            if isinstance(item, dict):
+                out.append(self._to_entry(item))
+        return out
+
+    def stat(self, api_path: str) -> RemoteEntry | None:
+        """Stat a single remote path without fetching content. None if missing."""
+        try:
+            data = self._request("GET", f"api/contents/{api_path}?content=0")
+        except ApiError as exc:
+            if exc.status == 404:
+                return None
+            raise
+        if isinstance(data, dict):
+            return self._to_entry(data)
+        return None
+
+    def hash(self, api_path: str) -> str | None:
+        """Return the server-computed **sha256** of a file WITHOUT downloading it.
+
+        Uses ``?content=0&hash=1`` -- the cheapest, most definitive remote
+        change-detection signal (research §1: identical to local ``shasum -a
+        256``, ~0.1 s even at 20 MiB). Returns None if the path is missing
+        (404), is a directory, or the server did not populate a sha256 hash
+        (older servers). Callers fall back to a content download in that case.
+        """
+        try:
+            data = self._request("GET", f"api/contents/{api_path}?content=0&hash=1")
+        except ApiError as exc:
+            if exc.status == 404:
+                return None
+            raise
+        if not isinstance(data, dict):
+            return None
+        algo = data.get("hash_algorithm")
+        digest = data.get("hash")
+        if digest and (algo is None or str(algo).lower() == "sha256"):
+            return str(digest)
+        return None
+
+    def get_file_bytes(self, api_path: str) -> bytes:
+        """Download a file's raw bytes, byte-faithfully.
+
+        We force ``type=file`` for EVERY path (including ``.ipynb``) so the
+        server treats the API as a plain byte store and does not normalize a
+        notebook through its JSON model (research §11). base64 ``content`` from
+        the server carries a trailing newline which we strip before decoding.
+        """
+        data = self._request("GET", f"api/contents/{api_path}?content=1&type=file")
+        if not isinstance(data, dict):
+            raise ApiError(f"unexpected response fetching {api_path}")
+        fmt = data.get("format")
+        content = data.get("content")
+        if fmt == "base64":
+            # The server appends a trailing "\n" to base64 content; strip ALL
+            # ASCII whitespace before decoding so we recover the exact bytes.
+            b64 = "".join(str(content or "").split())
+            return base64.b64decode(b64)
+        if fmt == "text":
+            return str(content or "").encode("utf-8")
+        if fmt == "json" or data.get("type") == "notebook":
+            # Should not happen now that we force type=file, but stay defensive:
+            # re-serialize a parsed model rather than crash.
+            return json.dumps(content, indent=1).encode("utf-8")
+        if content is None:
+            return b""
+        return str(content).encode("utf-8")
+
+    # --- write operations (caller MUST have asserted within prefix) ---------
+    def put_file_bytes(self, api_path: str, data: bytes) -> RemoteEntry:
+        """Upload raw bytes to ``api_path`` byte-faithfully (type=file).
+
+        Picks ``format=text`` for UTF-8 content (smaller, diffable) and
+        ``format=base64`` for binary/non-UTF-8 -- jp decides client-side because
+        the server does NOT reject binary sent as text (research §1, §11).
+        Parent dirs are auto-created by the server on PUT. Callers that need the
+        create-vs-update (201 vs 200) signal should use :meth:`put_file`, which
+        this method delegates to.
+        """
+        return self.put_file(api_path, data).entry
+
+    def put_file(self, api_path: str, data: bytes) -> PutResult:
+        """Like :meth:`put_file_bytes` but also reports create-vs-update.
+
+        Returns a :class:`PutResult` whose ``created`` is True on HTTP 201 (new
+        file) and False on HTTP 200 (overwrote) -- the empirical create/update
+        signal (research §2).
+        """
+        self._warn_if_large(api_path, len(data))
+        if _looks_utf8_text(data) and not _is_notebook_path(api_path):
+            body = {
+                "type": "file",
+                "format": "text",
+                "content": data.decode("utf-8"),
+            }
+        else:
+            # Notebooks and any non-UTF-8 bytes go up as base64 for fidelity.
+            body = {
+                "type": "file",
+                "format": "base64",
+                "content": base64.b64encode(data).decode("ascii"),
+            }
+        created, resp = self._request_status("PUT", f"api/contents/{api_path}", body=body)
+        if isinstance(resp, dict):
+            entry = self._to_entry(resp)
+        else:
+            entry = RemoteEntry(
+                name=api_path.rsplit("/", 1)[-1],
+                path=api_path,
+                type="file",
+                size=len(data),
+                last_modified="",
+            )
+        return PutResult(entry=entry, created=created)
+
+    def _warn_if_large(self, api_path: str, nbytes: int) -> None:
+        if nbytes >= self.large_file_warn_bytes and api_path not in self._warned_large:
+            self._warned_large.add(api_path)
+            mb = nbytes / (1024 * 1024)
+            ui.warn(
+                f"{api_path}: {mb:.0f} MiB will be sent as one in-memory request "
+                "(no chunking; base64 inflates ~33%); this may be slow or time out."
+            )
+
+    def _request_status(
+        self, method: str, api_path: str, body: dict[str, Any] | None = None
+    ) -> tuple[bool, Any]:
+        """Like :meth:`_request` but also returns whether the status was 201.
+
+        Used by PUT to distinguish 201 (created) from 200 (overwrote). We read
+        the status off the response object; on any non-2xx the normal error path
+        in :meth:`_request` would have raised, so we only reach here for 2xx.
+        """
+        url = self._url(api_path)
+        data = None
+        headers = {
+            "Authorization": f"token {self._token}",
+            "Accept": "application/json",
+        }
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(
+                req, timeout=self.timeout, context=self._ssl_context
+            ) as resp:
+                created = resp.status == 201
+                payload = resp.read()
+                if not payload:
+                    return created, None
+                ctype = resp.headers.get("Content-Type", "")
+                if "json" in ctype or payload[:1] in (b"{", b"["):
+                    return created, json.loads(payload.decode("utf-8"))
+                return created, payload
+        except urllib.error.HTTPError as exc:
+            self._raise_for_http(exc)
+        except urllib.error.URLError as exc:
+            raise NetworkError(f"network error talking to server: {exc.reason}") from exc
+        except (TimeoutError, OSError) as exc:
+            raise NetworkError(f"network error: {exc}") from exc
+        return False, None
+
+    def mkdir(self, api_path: str) -> None:
+        """Create a remote directory (idempotent-ish: 409/exists is tolerated).
+
+        Mostly defensive now -- PUT auto-creates parents (research §2). PATCH
+        does NOT, so callers that move into a new dir must mkdir it first.
+        """
+        try:
+            self._request("PUT", f"api/contents/{api_path}", body={"type": "directory"})
+        except ApiError as exc:
+            if exc.status in (409,):
+                return
+            raise
+
+    def rename(self, src_path: str, dst_path: str) -> RemoteEntry:
+        """Rename/move ``src_path`` to ``dst_path``.
+
+        PATCH does NOT auto-create the destination's parent (500 if missing) and
+        does NOT overwrite an existing target (409), so we mkdir the parent
+        first (research §3).
+        """
+        parent = dst_path.rsplit("/", 1)[0] if "/" in dst_path else ""
+        if parent:
+            self.mkdir(parent)
+        resp = self._request("PATCH", f"api/contents/{src_path}", body={"path": dst_path})
+        if isinstance(resp, dict):
+            return self._to_entry(resp)
+        return RemoteEntry(
+            name=dst_path.rsplit("/", 1)[-1],
+            path=dst_path,
+            type="file",
+            size=None,
+            last_modified="",
+        )
+
+    def delete(self, api_path: str) -> None:
+        """Delete a remote path. Used ONLY by ``jp rm`` (gated).
+
+        DELETE is NOT recursive on this server: a non-empty directory returns
+        400 "not empty" (research §5). ``jp rm --recursive`` walks bottom-up.
+        We re-raise the 400 with a clearer, actionable message.
+        """
+        try:
+            self._request("DELETE", f"api/contents/{api_path}")
+        except ApiError as exc:
+            if exc.status == 404:
+                return
+            if exc.status == 400 and "not empty" in exc.message.lower():
+                raise ApiError(
+                    f"refusing to delete non-empty directory {api_path!r}: "
+                    "the server is not recursive. Use 'jp rm --recursive' instead.",
+                    status=400,
+                ) from exc
+            raise
+
+    # --- health probe -------------------------------------------------------
+    def status_probe(self) -> StatusResult:
+        """Probe ``GET /api/status`` WITHOUT following redirects.
+
+        Decision table (research §8):
+          * 200            -> server up.
+          * 403 (JSON)     -> server up, token invalid/expired (AuthError).
+          * 3xx -> /hub/.. -> server stopped/not routed (ServerDownError).
+          * connection err -> network/Hub down (NetworkError).
+        """
+        url = f"{self.base_url}/api/status"
+        opener = urllib.request.build_opener(_NoRedirect, urllib.request.HTTPSHandler())
+        req = urllib.request.Request(
+            url,
+            headers={"Authorization": f"token {self._token}", "Accept": "application/json"},
+            method="GET",
+        )
+        try:
+            with opener.open(req, timeout=self.timeout) as resp:
+                return StatusResult(up=resp.status == 200, detail="reached /api/status")
+        except urllib.error.HTTPError as exc:
+            if exc.code in (301, 302, 303, 307, 308):
+                location = exc.headers.get("Location", "") if exc.headers else ""
+                if "/hub/" in location or "/hub" in location:
+                    raise ServerDownError() from exc
+                raise ServerDownError(
+                    f"unexpected redirect from /api/status to {location!r}; "
+                    "the server may be stopped -- start it from the JupyterHub UI."
+                ) from exc
+            if exc.code in (401, 403):
+                raise AuthError(
+                    "the server rejected the token (HTTP 403). "
+                    "Refresh your token via the JupyterHub UI and run 'jp login'."
+                ) from exc
+            self._raise_for_http(exc)
+        except urllib.error.URLError as exc:
+            raise NetworkError(f"could not reach the server: {exc.reason}") from exc
+        except (TimeoutError, OSError) as exc:
+            raise NetworkError(f"could not reach the server: {exc}") from exc
+        return StatusResult(up=False, detail="unknown")
+
+    # --- helpers ------------------------------------------------------------
+    @staticmethod
+    def _to_entry(item: dict[str, Any]) -> RemoteEntry:
+        return RemoteEntry(
+            name=str(item.get("name", "")),
+            path=str(item.get("path", "")),
+            type=str(item.get("type", "")),
+            size=item.get("size"),
+            last_modified=str(item.get("last_modified", "")),
+            mimetype=item.get("mimetype"),
+        )
+
+
+@dataclass
+class PutResult:
+    """Result of a PUT: the resulting entry plus the create-vs-update signal."""
+
+    entry: RemoteEntry
+    created: bool  # True on HTTP 201 (new file); False on HTTP 200 (overwrote)

jp/cli.py

@@ -0,0 +1,91 @@
+"""jp command-line entry point: argparse subcommands + safe error handling.
+
+Every command's ``run`` returns an exit code or raises a ``JpError``. This
+dispatcher translates exceptions into the the design docsexit codes and passes EVERY
+error message through ``ui.redact`` so a token can never leak via an error path.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from . import __version__, ui
+from .commands import ALL
+from .errors import EXIT_GENERIC, EXIT_OK, JpError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # Parent parser holds global flags shared by all subcommands.
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument("-q", "--quiet", action="store_true", help="suppress non-essential output")
+    parent.add_argument("--no-color", action="store_true", help="disable colored output")
+
+    parser = argparse.ArgumentParser(
+        prog="jp",
+        description="git-like safe sync between a local folder and a remote JupyterHub.",
+        parents=[parent],
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"jp {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+    subparsers.required = False
+
+    # Each command registers its own subparser, inheriting the global flags.
+    for mod in ALL:
+        # add_parser implementations create the subparser; we re-attach the
+        # parent flags so -q/--no-color work after the subcommand too.
+        mod.add_parser(_SubparsersWithParent(subparsers, parent))
+
+    return parser
+
+
+class _SubparsersWithParent:
+    """Wrap add_subparsers so each command's parser inherits global flags."""
+
+    def __init__(self, subparsers: argparse._SubParsersAction, parent: argparse.ArgumentParser):
+        self._subparsers = subparsers
+        self._parent = parent
+
+    def add_parser(self, name: str, **kwargs):
+        parents = list(kwargs.pop("parents", []))
+        parents.append(self._parent)
+        return self._subparsers.add_parser(name, parents=parents, **kwargs)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if getattr(args, "no_color", False):
+        import os
+
+        os.environ["JP_NO_COLOR"] = "1"
+    if getattr(args, "quiet", False):
+        ui.set_quiet(True)
+
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return EXIT_OK
+
+    try:
+        rc = func(args)
+        return int(rc) if rc is not None else EXIT_OK
+    except JpError as exc:
+        # Central redaction at the error boundary.
+        ui.error(exc.message)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        ui.error("interrupted")
+        return EXIT_GENERIC
+    except BrokenPipeError:  # pragma: no cover
+        return EXIT_OK
+    except Exception as exc:  # last-resort: never leak a token in a traceback line
+        ui.error(f"unexpected error: {exc}")
+        return EXIT_GENERIC
+
+
+if __name__ == "__main__":
+    sys.exit(main())