deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/output.py

@@ -0,0 +1,503 @@
+"""Output formatting helpers: JSON, table, and plain text."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import click
+
+
+def print_json(data: Any) -> None:
+    """Pretty-print *data* as JSON to stdout."""
+    click.echo(json.dumps(data, indent=2, ensure_ascii=False, default=str))
+
+
+def print_plain(text: str) -> None:
+    """Print plain text (markdown, XML, etc.) to stdout."""
+    click.echo(text)
+
+
+def print_table(rows: list[dict[str, Any]], columns: list[str] | None = None) -> None:
+    """Render *rows* as a Rich table to the terminal.
+
+    If *columns* is ``None`` the keys of the first row are used.
+    """
+    if not rows:
+        click.echo("(no results)")
+        return
+
+    from rich.console import Console
+    from rich.table import Table
+
+    # Some endpoints answer with a bare list of scalars (e.g. variant names).
+    # Wrap them so column derivation below doesn't call .keys() on a string.
+    if not isinstance(rows[0], dict):
+        rows = [{"value": r} for r in rows]
+
+    if columns is None:
+        columns = list(rows[0].keys())
+
+    table = Table(show_header=True, header_style="bold")
+    for col in columns:
+        table.add_column(col)
+
+    for row in rows:
+        table.add_row(*(str(row.get(c, "")) for c in columns))
+
+    Console().print(table)
+
+
+def _generated_id_lines(results: list[Any]) -> list[str]:
+    """One line per server-generated id in an applied `add_*` op.
+
+    `defs add-sheet` promises in its own help that "the generated sheetId comes
+    back in this command's output". The endpoint does return it, in
+    `results[].details.sheetId` — the plain formatter rendered only the op
+    count and the revision, so it was dropped in transit and the docstring was
+    describing an output nobody could see.
+
+    The id matters more here than in most responses: it is minted by the
+    server from a uuid, so it cannot be guessed or reconstructed, and it is the
+    argument every follow-up command needs (`add-block --sheet`,
+    `add-slide --deck`). Without it the next step is a `cat` or a `describe` to
+    read back what was just written.
+
+    Restricted to `add_*` ops and to keys ending in `Id`: every other op echoes
+    the ids it was *given*, and reprinting those would bury the one new fact in
+    a list of things the caller already typed.
+    """
+    lines: list[str] = []
+    for result in results:
+        if not isinstance(result, dict):
+            continue
+        kind = result.get("kind") or ""
+        if not (isinstance(kind, str) and kind.startswith("add_")):
+            continue
+        details = result.get("details")
+        if not isinstance(details, dict):
+            continue
+        minted = [
+            f"{k}={v}" for k, v in details.items()
+            if isinstance(k, str) and k.endswith("Id") and v
+        ]
+        if minted:
+            lines.append(f"  {kind}: {', '.join(minted)}")
+    return lines
+
+
+def _format_plain_dict(d: dict[str, Any]) -> str:
+    """Format a single dict concisely for plain output."""
+    # query value response: emit the value, or — when the cell resolved to no
+    # single value (empty, or populated under multiple statuses) — the per-status
+    # breakdown rather than a raw JSON blob.
+    if d.get("query_type") == "value" and isinstance(d.get("result"), dict):
+        res = d["result"]
+        val = res.get("value")
+        if val is not None:
+            return str(val)
+        vbs = res.get("values_by_status") or []
+        if vbs:
+            lines = (
+                ["(value differs by status — specify a status)"] if len(vbs) > 1 else []
+            )
+            lines += [f"{e.get('status_ref', '')}: {e.get('value', '')}" for e in vbs]
+            return "\n".join(lines)
+        return "(empty)"
+
+    # item_values response: context: value per line
+    if d.get("query_type") == "item_values" and isinstance(d.get("result"), list):
+        lines = [f"{r.get('context_ref', '')}: {r.get('value', '')}" for r in d["result"]]
+        truncated = d.get("truncated")
+        if truncated:
+            lines.append(f"... and {truncated} more")
+        return "\n".join(lines) if lines else "(no values)"
+
+    # edit/batch-edit and defs-ops response: summary + errors
+    if "results" in d and "errors" in d:
+        results = d["results"] if isinstance(d["results"], list) else []
+        n = len(results)
+        errs = d.get("errors", [])
+        # Defs-ops rows/errors carry `kind`; batch-edit rows carry cell refs.
+        is_ops = any(
+            isinstance(r, dict) and "kind" in r for r in results
+        ) or any(isinstance(e, dict) and "kind" in e for e in errs)
+        noun = "op" if is_ops else "edit"
+        rev = d.get("revision", d.get("rev", ""))
+        rev_part = f"  rev:{rev[:8]}" if rev else ""
+        if is_ops and d.get("success") is False:
+            # Whole-batch-atomic endpoints (/apply-defs-ops) return the
+            # in-memory successes in `results` even though the batch was
+            # discarded before persistence. Counting them as "applied" told
+            # the caller to retry only the failed op when the entire batch
+            # has to be re-sent.
+            #
+            # Gated on `is_ops`, NOT on `success` alone: /batch-edit sets
+            # `success = len(errors) == 0` and commits unconditionally
+            # (jingwei.py never reads it), so a partly-failed value edit landed
+            # here and told the caller "nothing was applied" about cells that
+            # are on disk — while stderr said the opposite and rev_part hid the
+            # revision that proves the write happened.
+            lines = [
+                f"batch rolled back: {n} {noun}(s) validated, "
+                f"{len(errs)} error(s) — nothing was applied"
+            ]
+        else:
+            lines = [f"{n} {noun}(s) applied{rev_part}"]
+            lines.extend(_generated_id_lines(results))
+        # Show auto-created contexts
+        auto = d.get("auto_created_contexts", [])
+        if auto:
+            lines.append(f"auto-created contexts: {', '.join(auto)}")
+        # Formulas this edit removed. Reported louder than an auto-created
+        # context because it cannot be undone from the document — the
+        # definition is gone, and this line is the only place the formula text
+        # is still written down.
+        for rem in d.get("calc_removals", []) or []:
+            if not isinstance(rem, dict):
+                continue
+            action = rem.get("action") or "removed"
+            calc_id = rem.get("calcId", "?")
+            formula = rem.get("formula")
+            if action == "narrowed":
+                lines.append(
+                    f"  removed formula from {rem.get('contextRef', '?')}: "
+                    f"{calc_id} no longer computes it "
+                    f"({rem.get('remainingContexts', '?')} period(s) left)")
+            else:
+                lines.append(f"  DELETED calculation {calc_id}")
+            if formula:
+                lines.append(f"    was: {formula}")
+            # A narrow that ALSO took a definition out entirely: two elements
+            # answered to one id and one of them named only this period, so
+            # narrowing it left nothing. "narrowed" is the right word for what
+            # the id still does; it is not the whole bill.
+            for gone in rem.get("deletedFormulas") or []:
+                lines.append(f"    also DELETED a definition of {calc_id}")
+                lines.append(f"      was: {gone}")
+        # Show individual error details — cell-addressed for value edits,
+        # kind/code-addressed for defs ops (which have no itemRef/contextRef).
+        for e in errs:
+            if not isinstance(e, dict):
+                lines.append(f"  error: {e}")
+                continue
+            reason = e.get("error") or e.get("message") or "unknown error"
+            if "itemRef" in e or "contextRef" in e:
+                lines.append(
+                    f"  error: {e.get('itemRef', '?')}[{e.get('contextRef', '?')}]: {reason}"
+                )
+            else:
+                kind = e.get("kind") or e.get("code") or "error"
+                code_part = f" [{e['code']}]" if e.get("code") and e.get("kind") else ""
+                lines.append(f"  error: {kind}{code_part}: {reason}")
+        # Show warnings (skip formula-mismatch noise)
+        for w in d.get("warnings", []):
+            if "mismatched values" in w:
+                continue
+            lines.append(f"  warning: {w}")
+        return "\n".join(lines)
+
+    # flat dict (no nested dicts/lists): key: value per line
+    if all(not isinstance(v, (dict, list)) for v in d.values()):
+        return "\n".join(f"{k}: {v}" for k, v in d.items())
+
+    # complex nested: compact JSON (no indent)
+    return json.dumps(d, ensure_ascii=False, default=str)
+
+
+def _format_plain_list(rows: list[Any]) -> str:
+    """Format a list concisely for plain output."""
+    if not rows:
+        return "(empty)"
+
+    # Non-dict items: one per line
+    if not isinstance(rows[0], dict):
+        return "\n".join(str(r) for r in rows)
+
+    keys = set(rows[0].keys())
+
+    # grep results: file:line:content
+    if {"file", "line", "content"} <= keys:
+        return "\n".join(
+            f"{r.get('file')}:{r.get('line')}:{r.get('content')}"
+            for r in rows
+        )
+
+    # git log / version log: sha[:8]  timestamp  message
+    if "sha" in keys or "revision" in keys:
+        lines: list[str] = []
+        for r in rows:
+            sha = str(r.get("sha") or r.get("revision", ""))[:8]
+            # The versions endpoint names the field `timestamp`; older shapes
+            # used date/created_at.
+            date = r.get("timestamp") or r.get("date") or r.get("created_at", "")
+            msg = r.get("message", r.get("description", ""))
+            lines.append(f"{sha}  {date}  {msg}")
+        return "\n".join(lines)
+
+    # file listings: one filename per line
+    if "filename" in keys or (keys == {"name"}):
+        name_key = "filename" if "filename" in keys else "name"
+        return "\n".join(str(r.get(name_key, "")) for r in rows)
+
+    # workspace list: slug per line, * for active, role when known (it
+    # decides push/merge/share rights)
+    if "slug" in keys:
+        lines = []
+        for r in rows:
+            marker = " *" if r.get("active") in (True, "*") else ""
+            role = r.get("role")
+            role_part = f"  {role}" if role else ""
+            lines.append(f"{r.get('slug')}{marker}{role_part}")
+        return "\n".join(lines)
+
+    # A row that carries an id ALONGSIDE a name: print both, id first.
+    #
+    # `ingest cn search` exists to turn a company name into a 6-digit code, and
+    # its rows are {code, name, org_id, exchange} — four keys, one of them
+    # `name`, so the small-dicts rule below printed the name and dropped the
+    # answer. The command echoed back what the caller had already typed.
+    #
+    # Generalised deliberately: whenever a row pairs a short identifier with a
+    # label, the identifier is the part the caller cannot type from memory and
+    # the part the next command takes as an argument.
+    if "code" in keys and "name" in keys:
+        lines = []
+        for r in rows:
+            exchange = r.get("exchange")
+            suffix = f" ({exchange})" if exchange and exchange != "?" else ""
+            lines.append(f"{r.get('code', '')}  {r.get('name', '')}{suffix}")
+        return "\n".join(lines)
+
+    # small dicts with name field
+    if "name" in keys and len(keys) <= 5:
+        return "\n".join(str(r.get("name", "")) for r in rows)
+
+    # fallback: first 3 scalar fields, tab-separated
+    cols = [k for k in rows[0] if not isinstance(rows[0][k], (dict, list))][:3]
+    if cols:
+        return "\n".join(
+            "\t".join(str(r.get(c, "")) for c in cols) for r in rows
+        )
+
+    return json.dumps(rows, ensure_ascii=False, default=str)
+
+
+def _format_plain(data: Any) -> str:
+    """Smart plain formatter: concise, token-saving output."""
+    if isinstance(data, str):
+        return data
+    if isinstance(data, list):
+        return _format_plain_list(data)
+    if isinstance(data, dict):
+        return _format_plain_dict(data)
+    return str(data)
+
+
+def output(data: Any, fmt: str = "plain") -> None:
+    """Dispatch to the right formatter.
+
+    *fmt* is one of ``json``, ``table``, ``plain``.
+    """
+    if fmt == "plain":
+        print_plain(_format_plain(data))
+    elif fmt == "table":
+        if isinstance(data, list):
+            print_table(data)
+        elif isinstance(data, dict):
+            print_table([data])
+        else:
+            print_plain(str(data))
+    else:
+        print_json(data)
+
+
+_SHA_LIKE_KEYS = frozenset({"revision", "rev", "commit_sha", "sha"})
+
+
+def output_mutation(data: Any, fmt: str, *, plain_key: str | None = "revision") -> None:
+    """Emit a mutation response.
+
+    In ``plain`` mode, stdout receives only ``data[plain_key]`` — SHA-like values
+    are sliced to 8 chars. ``echo_success`` on stderr carries the human summary,
+    keeping stdout machine-friendly. In ``json`` / ``table`` mode, delegates to
+    ``output()`` so the full structured payload is emitted unchanged.
+    """
+    if fmt != "plain":
+        output(data, fmt)
+        return
+    if plain_key is None or not isinstance(data, dict):
+        return
+    val = data.get(plain_key)
+    if val is None:
+        return
+    s = str(val)
+    if plain_key in _SHA_LIKE_KEYS:
+        s = s[:8]
+    click.echo(s)
+
+
+def _export_notes(raw: Any) -> list[dict]:
+    """Decode `X-Export-Notes` (base64 JSON list); [] on anything malformed."""
+    if not raw:
+        return []
+    try:
+        import base64
+
+        parsed = json.loads(base64.b64decode(str(raw)).decode("utf-8"))
+    except (ValueError, TypeError):
+        return []
+    return [n for n in parsed if isinstance(n, dict)] if isinstance(parsed, list) else []
+
+
+def echo_conversion_warnings(resp: Any) -> None:
+    """Surface header-borne export warnings from a binary-export response.
+
+    ``/to-excel`` and ``/to-pptx`` return the file as the body, so warnings
+    (failed recalc, chart fallbacks, …) ride in ``X-Conversion-Warnings``
+    (JSON list of messages, size-capped server-side) with the true total in
+    ``X-Conversion-Warnings-Count``. ``X-PPTX-Rasterized-Regions`` counts
+    slide regions exported as images instead of editable objects.
+    """
+    headers = getattr(resp, "headers", None) or {}
+
+    def _int_header(name: str) -> int:
+        try:
+            return int(headers.get(name, 0))
+        except (TypeError, ValueError):
+            return 0
+
+    count = _int_header("X-Conversion-Warnings-Count")
+    messages: list[Any] = []
+    raw = headers.get("X-Conversion-Warnings")
+    if raw:
+        try:
+            parsed = json.loads(raw)
+            if isinstance(parsed, list):
+                messages = parsed
+        except ValueError:
+            pass
+    # The structured notes (`X-Export-Notes`, base64 JSON), when the export
+    # sent them: grouped by slide and badged by fidelity, which is what a
+    # person deciding whether to ship the file wants to read. The string
+    # header stays for routes that have no notes (Excel, Word) and for a
+    # server that predates the header.
+    notes = _export_notes(headers.get("X-Export-Notes"))
+    if notes:
+        by_slide: dict[str, list[dict]] = {}
+        for note in notes:
+            where = str(note.get("slide_name") or note.get("slide_id") or "deck")
+            by_slide.setdefault(where, []).append(note)
+        for where, group in by_slide.items():
+            echo_warning(f"{where}:")
+            for note in group:
+                fidelity = str(note.get("fidelity") or "").strip()
+                badge = f"[{fidelity}] " if fidelity else ""
+                path = f"{note.get('path')} — " if note.get("path") else ""
+                echo_warning(f"  {badge}{path}{note.get('message') or note.get('code')}")
+        # Route-level warnings (a failed recalc, a scenario that did not
+        # apply) ride only the string header; print the ones the notes did
+        # not cover, in front, because those decide whether the numbers are
+        # right at all.
+        covered = {str(n.get("message") or "") for n in notes}
+        for m in messages:
+            text = str(m)
+            if not any(c and c in text for c in covered):
+                echo_warning(text)
+    else:
+        for m in messages:
+            echo_warning(str(m))
+    remaining = count - len(messages)
+    if remaining > 0:
+        suffix = "" if messages else " during export"
+        echo_warning(
+            f"...and {remaining} more conversion warning(s){suffix} — "
+            "see the server's conversion-warning logs"
+        )
+    rasterized = _int_header("X-PPTX-Rasterized-Regions")
+    if rasterized:
+        echo_info(
+            f"{rasterized} slide region(s) were rasterized (unsupported CSS "
+            "exported as images, not editable objects)"
+        )
+
+
+def echo_validation(data: Any) -> list[str]:
+    """Surface a file-write response's ``validation`` block on stderr.
+
+    The server persists invalid .deepcell content on purpose (computed values
+    stay fresh; errors ride along in ``validation``), so a write can succeed
+    AND carry errors. Prints every warning and error, and returns the errors
+    so the caller can refuse to exit 0.
+    """
+    if not isinstance(data, dict):
+        return []
+    validation = data.get("validation")
+    if not isinstance(validation, dict):
+        return []
+    for w in validation.get("warnings") or []:
+        echo_warning(str(w))
+    errors = [str(e) for e in validation.get("errors") or []]
+    for e in errors:
+        echo_error(f"Error: {e}")
+    return errors
+
+
+def echo_validation_map(validation: Any) -> list[str]:
+    """Surface a ``{filename: validation}`` map on stderr.
+
+    Multi-file write paths (``files:batch`` push, variant merge-back) report
+    validation per file rather than as a single block. Returns the filenames
+    that carry errors so the caller can refuse to exit 0.
+    """
+    invalid: list[str] = []
+    if not isinstance(validation, dict):
+        return invalid
+    for fname, info in validation.items():
+        if not isinstance(info, dict):
+            continue
+        for w in info.get("warnings") or []:
+            echo_warning(f"{fname}: {w}")
+        errors = info.get("errors") or []
+        for e in errors:
+            echo_error(f"{fname}: Error: {e}")
+        if errors:
+            invalid.append(str(fname))
+    return invalid
+
+
+def echo_success(message: str) -> None:
+    """Print a success message to stderr (so stdout stays machine-readable)."""
+    click.echo(click.style(f"✓ {message}", fg="green"), err=True)
+
+
+def echo_error(message: str) -> None:
+    """Print an error message to stderr."""
+    click.echo(click.style(f"✗ {message}", fg="red"), err=True)
+
+
+def echo_warning(message: str) -> None:
+    """Print a warning message to stderr."""
+    click.echo(click.style(f"⚠ {message}", fg="yellow"), err=True)
+
+
+def echo_info(message: str) -> None:
+    """Print an informational message to stderr."""
+    click.echo(message, err=True)
+
+
+def echo_query_back_hint(
+    filename: str, item: str | None = None, context: str | None = None
+) -> None:
+    """One-line R4 nudge after a value- or calc-affecting write.
+
+    R4 ("forecasts must populate — verify by query-back") is review-enforced,
+    so nothing in the command flow ever surfaced it: agents wrote values,
+    checked structure with describe/cat, and never read a number back. Emit
+    the exact query for the cell just touched at the one moment it is due.
+    """
+    echo_info(
+        f"→ verify: deepcell query {filename} {item or '<item>'} "
+        f"{context or '<context>'}  (rules R4: read the changed values back)"
+    )

deepcell_cli/revision.py

@@ -0,0 +1,164 @@
+"""Optimistic-lock (compare-and-swap) plumbing shared by the write commands.
+
+Several commands are a fetch-XML → transform → write-back round trip:
+Every ``reasoning add-*``/``update-*``,
+``edit``, ``defs apply``, and ``replace``'s legacy fallback. Each one has a
+lost-update window — whatever landed between the fetch and the write is
+silently overwritten (#1217).
+
+Closing it needs two things at every such site, which is why they live here
+rather than being re-typed per command:
+
+* the revision of the bytes that were fetched — a response *header*, so the
+  plain JSON body does not carry it (:meth:`APIClient.get_with_revision`);
+* one rendering of the server's 409, so a conflict reads the same whichever
+  command hit it.
+
+The second point carries a distinction worth keeping: a 409 means either that
+the file itself moved (``stale_revision`` — the change was dropped and must be
+re-applied by hand) or that only the workspace's commit lock was contended
+(``concurrent_write`` — the file is untouched and re-running is safe). Handing
+either message to the other caller is wrong, one as busywork and one as data
+loss, so the reason is read from the server's ``X-Conflict-Reason`` header
+rather than guessed from the wording of ``detail``.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+def fetch_xml_with_revision(ctx, slug: str, filename: str) -> tuple[str, str | None]:
+    """Read a workspace file's XML plus the revision it was read at.
+
+    A missing revision is not an error: an older server does not send the
+    header, and the caller then writes unguarded exactly as it did before.
+    """
+    data, revision = ctx.client.get_with_revision(f"/workspaces/{slug}/files/{filename}")
+    xml = data.get("content", "") if isinstance(data, dict) else ""
+    if not xml:
+        raise click.ClickException(f"File '{filename}' is empty or not found.")
+    return xml, revision
+
+
+def write_body(content: str, revision: str | None, **extra) -> dict:
+    """Build the workspace-write body, including the CAS token when we have one."""
+    body: dict = {"content": content}
+    if revision:
+        body["expected_revision"] = revision
+    body.update({k: v for k, v in extra.items() if v is not None})
+    return body
+
+
+# Mirrors jingwei_api/conflict.py — the server's machine-readable answer to
+# "why did this 409?". Keep the two in sync; they are one contract.
+CONFLICT_REASON_HEADER = "x-conflict-reason"
+CURRENT_REVISION_HEADER = "x-current-revision"
+REASON_STALE_REVISION = "stale_revision"
+REASON_CONCURRENT_WRITE = "concurrent_write"
+
+
+def _header(exc, name: str) -> str | None:
+    """Case-insensitive header read off an :class:`APIError`.
+
+    httpx lowercases header names on the way in, but nothing guarantees the
+    caller built the error that way (tests construct them by hand), so the
+    lookup does not depend on it.
+    """
+    headers = getattr(exc, "headers", None) or {}
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+def conflict_reason(exc) -> str | None:
+    """The server's reason for a 409, or None if this is not one we handle.
+
+    Two sources, because the write surfaces disagree on where they put it: the
+    ``/workspaces/.../files`` family sends a structured ``detail`` body,
+    ``/batch-edit`` and ``/apply-defs-ops`` send the header only. The header is
+    checked first — it is the one signal every surface now emits.
+    """
+    if getattr(exc, "status_code", None) != 409:
+        return None
+    reason = _header(exc, CONFLICT_REASON_HEADER)
+    if reason:
+        return reason
+    payload = getattr(exc, "payload", None)
+    if isinstance(payload, dict):
+        return payload.get("reason")
+    return None
+
+
+def format_stale_revision(payload: dict, *, filename: str | None = None) -> str:
+    """Render the server's ``stale_revision`` 409 into an actionable message."""
+    current = payload.get("current_revision")
+    who = f"'{filename}'" if filename else "The file"
+    lines = [
+        f"{who} changed since you read it"
+        + (f" (current revision: {current})." if current else ".")
+    ]
+    lines.append(
+        "Your change was NOT saved. Re-read the file and re-apply it — "
+        "replaying it onto the newer document would drop whoever wrote in "
+        "between."
+    )
+    hint = payload.get("hint")
+    if hint:
+        lines.append(f"Hint: {hint}")
+    return "\n".join(lines)
+
+
+def format_concurrent_write(
+    current: str | None, *, filename: str | None = None
+) -> str:
+    """Render a ``concurrent_write`` 409.
+
+    Deliberately a different message from :func:`format_stale_revision`, and
+    the difference is the whole point: here the file is byte-identical to what
+    the caller read and only the workspace's commit lock was contended, so
+    re-running the same command is correct rather than destructive. Telling
+    this caller to "re-read and re-apply" would be busywork, and telling the
+    stale caller to "just re-run" would silently drop someone's edit.
+    """
+    who = f"'{filename}'" if filename else "The file"
+    lines = [
+        f"{who} was not written: the workspace is being committed to "
+        "concurrently."
+    ]
+    lines.append(
+        "Nothing was lost and your file is unchanged — re-run the same command."
+    )
+    if current:
+        lines.append(f"(workspace is at revision {current})")
+    return "\n".join(lines)
+
+
+def raise_if_stale(exc, *, filename: str | None = None) -> None:
+    """Turn a write-conflict :class:`APIError` into a clean ``ClickException``.
+
+    Any other error is left alone for the caller to re-raise, so this never
+    swallows an unrelated 409 (``files:replace`` also 409s on *no match* and on
+    an *ambiguous* match).
+    """
+    reason = conflict_reason(exc)
+    if reason == REASON_STALE_REVISION:
+        payload = getattr(exc, "payload", None)
+        payload = payload if isinstance(payload, dict) else {}
+        # The header is the fallback for the surfaces that send no structured
+        # body, so the revision reaches the message either way.
+        if not payload.get("current_revision"):
+            payload = {
+                **payload,
+                "current_revision": _header(exc, CURRENT_REVISION_HEADER),
+            }
+        raise click.ClickException(
+            format_stale_revision(payload, filename=filename)
+        ) from exc
+    if reason == REASON_CONCURRENT_WRITE:
+        raise click.ClickException(
+            format_concurrent_write(
+                _header(exc, CURRENT_REVISION_HEADER), filename=filename
+            )
+        ) from exc