recala-cli 0.6.0__py3-none-any.whl

recala_cli/errors.py

@@ -0,0 +1,220 @@
+"""How a failure is named: one stable exit code and one machine-readable code.
+
+Agents branch on the exit code, so a number never changes meaning once shipped.
+Add new codes at the end; never reuse or renumber one.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Any
+
+import httpx
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    ERROR = 1  # unexpected: a bug, or an answer the CLI cannot read
+    USAGE = 2  # bad flags or arguments (click uses 2 for these too)
+    NOT_AUTHENTICATED = 3  # no credentials, or the API refused them
+    FORBIDDEN = 4  # the role or the key's scopes do not allow it
+    NOT_FOUND = 5
+    CONFLICT = 6  # the current state does not allow it yet (no org selected, no person linked)
+    INVALID = 7  # the API refused the input (400, 422)
+    RATE_LIMITED = 8  # retry after a pause
+    UNAVAILABLE = 9  # server or network trouble; safe to retry
+    CONFIRMATION_REQUIRED = 10  # a guarded action (publish, pay) ran without its confirmation flag
+    PAYMENT_REQUIRED = 11  # not enough credits for a paid action
+
+
+_BY_STATUS: dict[int, tuple[ExitCode, str]] = {
+    400: (ExitCode.INVALID, "invalid"),
+    401: (ExitCode.NOT_AUTHENTICATED, "not_authenticated"),
+    402: (ExitCode.PAYMENT_REQUIRED, "payment_required"),
+    403: (ExitCode.FORBIDDEN, "forbidden"),
+    404: (ExitCode.NOT_FOUND, "not_found"),
+    409: (ExitCode.CONFLICT, "conflict"),
+    422: (ExitCode.INVALID, "invalid"),
+    429: (ExitCode.RATE_LIMITED, "rate_limited"),
+}
+_RETRYABLE = {ExitCode.RATE_LIMITED, ExitCode.UNAVAILABLE}
+# A gateway (Railway, Cloudflare) answering for an API that did not: always a passing outage.
+_GATEWAY_STATUSES = {502, 504, 520, 521, 522, 523, 524}
+TRY_AGAIN = "try again in a minute."
+OUTAGE_NEXT_STEP = f"Recala is not answering right now; {TRY_AGAIN}"
+SUPPORT_EMAIL = "hello@recala.co"  # the address the product tells people to write to
+SERVER_PROBLEM = (f"Recala hit a problem on its side. Try again in a minute; if it keeps failing, write to {SUPPORT_EMAIL}")
+# A 5xx whose words are a setting ("not enabled", "not configured"), not a failure, keeps its own sentence.
+_SETTING_WORDS = ("not enabled", "not configured")
+CHECK_FIRST = "this change may have gone through. Check it before you try again."
+# Failures before the request left this machine: trying again cannot repeat a write.
+_NEVER_SENT = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)
+
+
+class CliError(Exception):
+    """A failure the CLI reports and exits on, never a traceback."""
+
+    def __init__(self, exit_code: ExitCode, code: str, message: str, status: int | None = None,
+                 details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.code = code
+        self.message = message
+        self.status = status
+        self.details = details
+
+    @property
+    def retryable(self) -> bool:
+        # A paid call with an unknown outcome is never "retry": the caller checks the state first.
+        return self.exit_code in _RETRYABLE and self.code not in {"outcome_unknown", "run_continues", "still_waiting", "method_search_quota_ledger_blocked"}
+
+    def as_dict(self) -> dict[str, Any]:
+        envelope = {
+            "code": self.code,
+            "message": self.message,
+            "status": self.status,
+            "exit_code": int(self.exit_code),
+            "retryable": self.retryable,
+        }
+        if self.details is not None:
+            envelope["details"] = self.details  # the API's own structured refusal, for agents to read
+        return envelope
+
+
+class DryRunStop(Exception):
+    """--dry-run reached the first write: stop before it, and say what it would have been (not a failure)."""
+
+    def __init__(self, would: str) -> None:
+        super().__init__(would)
+        self.would = would
+
+
+def session_expired(status: int | None = None, *, code: str = "session_expired") -> CliError:
+    return CliError(ExitCode.NOT_AUTHENTICATED, code, "Your sign-in expired. Run `recala login`.", status)
+
+
+def error_from_response(response: httpx.Response, *, writes: bool = False) -> CliError:
+    """Classify an API refusal.
+
+    The API's own code wins over the generic name: FastAPI's ``detail.code``, or
+    the OAuth-style ``error`` the device sign-in answers with (RFC 8628).
+    """
+    if writes and _not_the_api_answering(response):
+        return CliError(ExitCode.UNAVAILABLE, "outcome_unknown",
+                        f"Recala did not finish answering (HTTP {response.status_code}); {CHECK_FIRST}",
+                        status=response.status_code)
+    if response.status_code >= 500:
+        exit_code, code = ExitCode.UNAVAILABLE, "unavailable"
+    else:
+        exit_code, code = _BY_STATUS.get(response.status_code, (ExitCode.ERROR, "error"))
+    detail = _detail_of(response)
+    if response.status_code >= 500 and _is_a_failure_not_a_setting(detail):
+        raw = detail if isinstance(detail, str) and detail.strip() and _readable(response) else None
+        return CliError(exit_code, code, SERVER_PROBLEM, status=response.status_code,
+                        details={"server_message": raw[:300]} if raw else None)
+    if isinstance(detail, dict):
+        code = str(detail.get("code") or detail.get("error") or code)
+        if code == "api_keys_disabled":
+            return CliError(exit_code, code, "API keys are not enabled for this company yet",
+                            status=response.status_code, details=detail)
+        if code == "topic_not_approved":
+            message = f"{TOPIC_NOT_APPROVED}\nNext: {approve_topic_command(str(detail.get('queue_id') or ''))}"
+            return CliError(exit_code, code, message, status=response.status_code, details=detail)
+        message = str(detail.get("message") or detail.get("error_description") or _summary(code, detail))
+        if _passing_outage(response):
+            message = f"{message} {_when_to_try_again(response)}"
+        return CliError(exit_code, code, message, status=response.status_code, details=detail)
+    if isinstance(detail, list):  # FastAPI's validation errors: the field and why, never the value sent
+        message = "; ".join(_field_error(item) for item in detail) or response.reason_phrase
+    else:
+        message = str(detail) if detail else response.reason_phrase
+    return CliError(exit_code, code, message, status=response.status_code)
+
+
+#: The API's topic gate (review/queue_gate.py): this company writes only topics a person approved.
+TOPIC_NOT_APPROVED = "This company approves topics before they are written, and this one is not approved yet."
+
+
+def approve_topic_command(queue_id: str) -> str:
+    return f"recala topics approve {queue_id[:8]}"
+
+
+def network_failure(failure: httpx.HTTPError, *, writes: bool) -> CliError:
+    """No answer: a read, or a request that never left, may be tried again; a write may already have landed."""
+    name = failure.__class__.__name__
+    if not writes or isinstance(failure, _NEVER_SENT):
+        return CliError(ExitCode.UNAVAILABLE, "unavailable", f"Could not reach the Recala API ({name}); {TRY_AGAIN}")
+    return CliError(ExitCode.UNAVAILABLE, "outcome_unknown", f"No answer from the Recala API ({name}); {CHECK_FIRST}")
+
+
+def _is_a_failure_not_a_setting(detail: Any) -> bool:
+    """Any 5xx is Recala's problem, never the person's: only a structured refusal or a switched-off feature speaks for itself."""
+    if isinstance(detail, dict):
+        return False
+    return not (isinstance(detail, str) and any(word in detail.lower() for word in _SETTING_WORDS))
+
+
+def _when_to_try_again(response: httpx.Response) -> str:
+    seconds = response.headers.get("retry-after", "")
+    minutes = -(-int(seconds) // 60) if seconds.isdigit() else 1
+    return "Try again in a minute." if minutes <= 1 else f"Try again in about {minutes} minutes."
+
+
+def _field_error(item: Any) -> str:
+    if not isinstance(item, dict):
+        return "invalid input"
+    where = ".".join(str(part) for part in item.get("loc") or [] if part != "body")
+    return f"{where}: {item.get('msg')}" if where else str(item.get("msg") or "invalid input")
+
+
+def _summary(code: str, detail: dict[str, Any]) -> str:
+    """A sentence for a refusal the API sent as data only (never a raw dict on a person's screen)."""
+    reasons = []
+    policy = detail.get("publication_policy")
+    if isinstance(policy, dict):
+        for violation in policy.get("violations") or []:
+            if isinstance(violation, dict):
+                reasons.append(f"{violation.get('url') or 'a source'} ({violation.get('reason')})")
+    for key in ("blockers", "reasons"):
+        reasons.extend(str(item) for item in detail.get(key) or [] if isinstance(item, str))
+    text = f"Recala refused this: {code.replace('_', ' ')}"
+    return text + (": " + "; ".join(reasons[:4]) if reasons else "") + "."
+
+
+def _passing_outage(response: httpx.Response) -> bool:
+    """A gateway's answer, or a 503 that says when to retry; a 503 for a switched-off feature is not one."""
+    return _from_a_gateway(response) or (response.status_code == 503 and "retry-after" in response.headers)
+
+
+def _not_the_api_answering(response: httpx.Response) -> bool:
+    """A gateway's answer, or a crash page: the API may have done the work before the answer was lost."""
+    return _from_a_gateway(response) or (response.status_code >= 500 and not _readable(response))
+
+
+def _from_a_gateway(response: httpx.Response) -> bool:
+    """A gateway status whose body is not the API's: its own 502s (a failed CMS take-down) carry ``detail``."""
+    return response.status_code in _GATEWAY_STATUSES and not _api_detail_in(response)
+
+
+def _api_detail_in(response: httpx.Response) -> bool:
+    try:
+        body = response.json()
+    except ValueError:
+        return False
+    return isinstance(body, dict) and "detail" in body
+
+
+def _readable(response: httpx.Response) -> bool:
+    try:
+        response.json()
+    except ValueError:
+        return False
+    return True
+
+
+def _detail_of(response: httpx.Response) -> Any:
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text[:300]
+    return body.get("detail", body) if isinstance(body, dict) else body

recala_cli/human.py

@@ -0,0 +1,324 @@
+"""Readable views of nested results; Python container repr never reaches a person."""
+
+import re
+from typing import Any
+
+from recala_cli.errors import TOPIC_NOT_APPROVED, approve_topic_command
+
+
+def publish_state_words(state: str | None) -> str:
+    """A publishing state in words: "draft" is only the default for an article that is not published yet."""
+    return "not published" if state in (None, "", "draft") else str(state).replace("_", " ")
+
+
+def describe_comments(listed: dict[str, Any]) -> str:
+    """Review-link comments: who asked what, on which words, and whether it is still open."""
+    comments = listed.get("comments") or []
+    if not comments:
+        return "No comments from the review link yet."
+    still_open = sum(1 for comment in comments if (comment.get("status") or "open") == "open")
+    lines = [f"{len(comments)} comment{'' if len(comments) == 1 else 's'}, {still_open} open:"]
+    for comment in comments:
+        passage = (comment.get("quote") or {}).get("exact")  # the API nests the commented words under "quote"
+        where = f' on "{passage}"' if passage else ""
+        state = str(comment.get("status") or "open").replace("_", " ").capitalize()
+        lines.append(f"  {state} · {comment.get('author_name') or 'A reviewer'}{where}: {comment.get('body')}")
+    return "\n".join(lines)
+
+
+def describe_fields(result: Any) -> str:
+    """Keep the result's information in labelled lines, including nested records."""
+    if isinstance(result, dict):
+        lines = []
+        for key, value in result.items():
+            if value is None:
+                continue  # an empty fact is left out, not printed as "not available"
+            label = str(key).replace("_", " ").capitalize()
+            text = describe_fields(value)
+            if isinstance(value, (dict, list)):
+                lines.append(f"{label}:\n" + "\n".join(f"  {line}" for line in text.splitlines()))
+            else:
+                lines.append(f"{label}: {text}")
+        return "\n".join(lines) or "No details available."
+    if isinstance(result, list):
+        return "\n".join(describe_fields(value) for value in result) or "None."
+    if result is None:
+        return "not available"
+    if isinstance(result, bool):
+        return "yes" if result else "no"
+    return str(result)
+
+
+def describe_local_fields(ctx: Any, result: Any) -> str:
+    """describe_fields with each instant in the company's timezone, named once above when any appears."""
+    from recala_cli.views import company_timezone, localise_instants, timezone_label
+
+    if not localise_instants(result, "UTC")[1]:
+        return describe_fields(result)  # no instant: no timezone lookup
+    zone = company_timezone(ctx, result if isinstance(result, dict) else {})
+    return f"{timezone_label(zone)}\n{describe_fields(localise_instants(result, zone)[0])}"
+
+
+def describe_edit(result: dict[str, Any]) -> str:
+    redraft = result.get("redraft")
+    if isinstance(redraft, dict):
+        if redraft.get("applied"):
+            return "Kept the AI draft's changes."
+        if redraft.get("status") == "completed" and isinstance(redraft.get("summary"), dict):
+            return describe_finished_redraft(redraft)
+        return f"AI draft: {redraft.get('status') or 'ready'}." + (f" {redraft['summary']}" if redraft.get("summary") else "")
+    return "Updated the article's text."
+
+
+def describe_finished_redraft(redraft: dict[str, Any]) -> str:
+    """The numbered notes --undo refers to, what each did, what the AI could not answer, and how to keep it."""
+    summary, notes = redraft["summary"], redraft.get("notes") or []
+    partly = summary.get("notes_partially_applied") or 0
+    lines = [f"AI draft ready: {summary.get('notes_applied', 0)} of {len(notes)} notes applied"
+             + (f", {partly} in part" if partly else "")
+             + f"; {summary.get('words_added', 0)} words added, {summary.get('words_removed', 0)} removed."]
+    for note in notes:
+        changed = [section["heading"] for section in note.get("sections") or [] if section.get("changed")]
+        line = f"  {note.get('index')}. {note.get('text')}: {str(note.get('status') or 'pending').replace('_', ' ')}"
+        line += f" ({', '.join(changed)})" if changed else ""
+        line += f". {note['status_reason']}" if note.get("status_reason") else ""
+        lines.append(line)
+    lines += [f"Open question: {item['question']}" for question in redraft.get("questions") or []
+              for item in question.get("items") or [] if item.get("question")]
+    if notes and redraft.get("article_id"):
+        identifier = str(redraft["article_id"])[:8]
+        lines.append(f"Next: keep it with recala article edit {identifier} --apply (this also hands it over for review), "
+                     "or keep some with --apply --undo <numbers>")
+    return "\n".join(lines)
+
+
+def describe_schedule(result: dict[str, Any]) -> str:
+    if result.get("dry_run"):
+        readiness = "ready" if result.get("can_schedule") else "not ready"
+        blockers = describe_fields(result.get("blockers") or [])
+        return f"Scheduling preview: {readiness}.\nTimezone: {result.get('timezone') or 'UTC'}\nBlockers: {blockers}"
+    appointment = result.get("appointment") or {}
+    return "Scheduled the article." + (f" Publication: {appointment['scheduled_at']}." if appointment.get("scheduled_at") else "")
+
+
+_COST_BLOCKERS = {
+    "topic_not_found": "This topic could not be found.",
+    "topic_not_writable": "This topic is not ready for a new article.",
+    "topic_not_approved": TOPIC_NOT_APPROVED,
+    "topic_dismissed": "This topic was dismissed.",
+    "managed_monthly_cap_reached": "Your managed plan has reached its monthly article limit.",
+    "no_article_credit": "No articles are left on your plan.",
+    "api_key_credit_cap_reached": "This API key has reached its article spending limit.",
+}
+
+
+def describe_cost_refusal(preview: dict[str, Any]) -> str:
+    blockers = preview.get("blockers") or ["request_refused"]
+    sentences = [_COST_BLOCKERS.get(code) or str(code).replace("_", " ").capitalize().rstrip(".") + "."
+                 for code in blockers]
+    return "Not possible now: " + " ".join(sentences) + f"\nNext: {_step_past(blockers, str(preview.get('target') or ''))}"
+
+
+def _step_past(blockers: list[str], target: str) -> str:
+    """The one command that clears the first thing in the way."""
+    if "topic_not_approved" in blockers:
+        return approve_topic_command(target)
+    if any(code in {"topic_not_found", "topic_not_writable", "topic_dismissed"} for code in blockers):
+        return "recala topics list"
+    return "recala credits"
+
+
+def cost_sentence(preview: dict[str, Any]) -> str:
+    payment = preview.get("payment") or {}
+    usage = preview.get("managed_usage") or {}
+    return {
+        "credit": f"uses 1 of your plan's articles ({payment.get('available', 'unknown')} left)",
+        "internal": "included in your plan at no charge",
+        "managed": f"counts toward your managed plan ({usage.get('used', 'unknown')} of {usage.get('cap', 'unknown')} this month)",
+        "none_left": "no articles left on your plan",
+    }.get(payment.get("how"), "the balance could not be read")
+
+
+def describe_creation(result: dict[str, Any], *, topic_label: str | None = None) -> str:
+    if result.get("dry_run"):
+        preview = result.get("preview") or {}
+        identifier = str(preview.get("target") or "")[:8]
+        label = topic_label or f"topic [{identifier}]"
+        lines = [f"Write {label}: {cost_sentence(preview)}."]
+        lines.append(describe_cost_refusal(preview) if preview.get("allowed") is False else
+                     f"Next: recala article create --topic {identifier}")
+        return "\n".join(lines)
+    identifier = result.get("article_id") or result.get("id")
+    title = result.get("title") or result.get("topic") or "article"
+    return f"Created {title} [{str(identifier)[:8]}]." if identifier else "Created the article."
+
+
+#: Finding kinds the writer's gates emit (api authority/quality/gates/*.py: fabrication, slice_grounding,
+#: stale_or_unsourced_claim, inline_source, company_figures), as "kind: item, item". Each reads as what to fix.
+_FINDING_KINDS = {
+    "figures": ("The {noun} {items} {be} not in your sources.", "Add the source or take the number out."),
+    "unconfirmed figures": ("Recala could not confirm {items} against your sources.",
+                            "Add the source or take the number out."),
+    "entities": ("{items} {be} named but not found in your sources.", "Add a source for it or remove the name."),
+    "superlatives": ("Your sources do not back this claim: {items}.", "Soften the claim or add evidence."),
+    "numbers absent from cited evidence": ("{items} {be} not in the evidence the article cites.",
+                                           "Cite evidence that contains the number, or remove it."),
+    "unsourced first-party figures": ("Your own figures {items} need a source.", "Cite where they come from."),
+    "self-citation as evidence": ("{items} rest only on your own site.", "Add an independent source."),
+    "quoted sentences naming no pack-backed source": ("These quotes name no source Recala has: {items}.",
+                                                      "Name the source or remove the quote."),
+    "external figures with no inline source": ("These outside figures have no source beside them: {items}.",
+                                               "Put the source next to each figure."),
+    "sources-block urls the pack cannot stand up": ("These links in the sources list could not be confirmed: {items}.",
+                                                    "Replace them with links Recala can reach."),
+}
+_KIND_LABEL = "|".join(sorted((re.escape(kind) for kind in _FINDING_KINDS), key=len, reverse=True))
+_FINDING_START = re.compile(rf"(?i)(?:^|(?<=[;|])\s*)(?=(?:{_KIND_LABEL})(?: \([^)]*\))?: )")
+_FINDING = re.compile(rf"(?is)^({_KIND_LABEL})(?: \([^)]*\))?:\s*(.+)$")
+_UNKNOWN_KIND = re.compile(r"^([a-z][a-z0-9]*(?:_[a-z0-9]+)+):\s*(.+)$")
+_FIGURE_TRIPLE = re.compile(
+    r"^(?P<value>[−+-]?\d[\d.,]*) (?P<kind>[a-z][a-z0-9_]*(?::[^\s]+)?) "
+    r"(?P<bound>exact|gte|gt|lte|lt|unlikely_\w+)$")
+_BOUNDS = {"exact": "", "gte": "at least ", "gt": "more than ", "lte": "at most ", "lt": "fewer than "}
+_PLURAL_UNITS = {"day": "days", "week": "weeks", "month": "months", "year": "years", "hour": "hours",
+                 "minute": "minutes", "second": "seconds", "lesson": "lessons", "gem": "gems", "streak": "streaks"}
+_CURRENCY = {"eur": "€", "usd": "$", "gbp": "£"}
+
+
+def _figure_words(raw: str) -> str:
+    """'1230 count:machine exact' as '1,230 machines'; anything that is not a signature is kept as written."""
+    match = _FIGURE_TRIPLE.match(raw.strip())
+    if not match:
+        return raw.strip()
+    value, kind, bound = match["value"], match["kind"], match["bound"]
+    try:
+        number = float(value.replace(",", ""))
+        if number == int(number) and re.fullmatch(r"\d+", value):
+            value = f"{int(number):,}"
+    except ValueError:
+        pass
+    category, _, name = kind.partition(":")
+    if kind == "percent":
+        unit = "%"
+    elif category == "currency":
+        unit = _CURRENCY.get(name, name.upper())
+    elif category == "count":
+        unit = name if name.endswith("s") else name + "s"
+    elif not name:
+        unit = _PLURAL_UNITS.get(kind, kind.replace("_", " "))
+    else:
+        unit = name
+    prefix = _BOUNDS.get(bound, "not " + bound.removeprefix("unlikely_") + " ")
+    joined = f"{value}{unit}" if unit in ("%",) else f"{value} {unit}"
+    return prefix + joined
+
+
+def _list_in_words(items: list[str]) -> str:
+    return items[0] if len(items) == 1 else ", ".join(items[:-1]) + " and " + items[-1]
+
+
+def finding_sentences(detail: str) -> list[str]:
+    """A hold's machine detail as sentences: one per finding kind; text that is already a sentence is kept."""
+    pieces = [part for part in re.split(_FINDING_START, detail) if part and part.strip(" ;|")]
+    sentences = []
+    for piece in pieces:
+        piece = piece.strip(" ;|")
+        found = _FINDING.match(piece)
+        unknown = _UNKNOWN_KIND.match(piece)
+        if found:
+            kind = found[1].lower()
+            items = [_figure_words(item) for item in re.split(r",\s*(?![^()]*\))", found[2].strip()) if item.strip()]
+            if kind in ("figures", "unconfirmed figures", "unsourced first-party figures"):
+                noun = "figure" if len(items) == 1 else "figures"
+            else:
+                noun = "name" if len(items) == 1 else "names"
+            body, advice = _FINDING_KINDS[kind]
+            joined = _list_in_words(items) if kind == "figures" else ", ".join(items)
+            sentences.append(" ".join(body.format(noun=noun, items=joined, be="is" if len(items) == 1 else "are")
+                                      .split()) + " " + advice)
+        elif unknown:
+            sentences.append(f"Recala's checks flagged {unknown[1].replace('_', ' ')}: {unknown[2].strip()}. "
+                             "Review that part of the text.")
+        else:
+            sentences.append(piece)
+    return sentences
+
+
+_RECHECK_METHOD_CODES = {"method_final_checks_failed", "method_edit_ledger_invalid"}
+RECHECK_VERDICT_CODES = _RECHECK_METHOD_CODES | {"author_checks_failed", "recheck_blocked"}
+_SAVED_TEXT_NOTICE = "Your saved text has not changed."
+
+
+def _message_findings(code: str, message: str, *, split_message: bool = False) -> list[str]:
+    """Keep separators and context so parsing cannot silently discard diagnostic text."""
+    text = re.sub(r"(?:^|\s+)" + re.escape(_SAVED_TEXT_NOTICE) + r"\s*$", "", message).strip()
+    if code in _RECHECK_METHOD_CODES or split_message:
+        bullets = list(re.finditer(r"(?m)^- ", text))
+        if bullets:
+            # The header belongs to the first claim; any trailing context belongs to the last.
+            starts = [0, *(match.start() for match in bullets[1:]), len(text)]
+            return [text[start:end].strip() for start, end in zip(starts, starts[1:])]
+        return [part.strip() for part in re.split(r"(?<=;) ", text) if part.strip()]
+    return [text] if text else []
+
+
+def _finding_record(item: Any, index: int) -> dict[str, Any]:
+    metadata = {}
+    if isinstance(item, dict):
+        metadata = {key: item[key] for key in ("claim_id", "section", "claim_text", "code") if item.get(key) is not None}
+        parts = [str(item[key]) for key in ("text", "meaning", "found", "detail") if item.get(key)]
+        text = " ".join(dict.fromkeys(parts))
+        claim_text = item.get("claim_text")
+        if claim_text and str(claim_text) not in text:
+            text = f"«{claim_text}» " + text
+        location = ", ".join(str(value) for value in (item.get("section"),
+                             f"claim {item['claim_id']}" if item.get("claim_id") is not None else None) if value)
+        text = (location + ": " if location else "") + (text or str(item.get("code") or describe_fields(item)))
+    else:
+        text = str(item)
+        claim = re.search(r"(?:^|\n)(?:- |Check )?([^\n]+?), claim (\d+): «([^»]*)»", text)
+        if claim:
+            metadata = {"section": claim[1], "claim_id": int(claim[2]), "claim_text": claim[3]}
+    return {"index": index, "text": text.strip(), **metadata}
+
+
+def recheck_findings(code: str, message: str, details: dict[str, Any], *,
+                     split_message: bool = False) -> list[dict[str, Any]]:
+    """Prefer server records, then legacy failures, then only documented message boundaries."""
+    items = details.get("findings") or details.get("failures")
+    if not isinstance(items, list) or not items:
+        items = _message_findings(code, message, split_message=split_message)
+    return [_finding_record(item, index) for index, item in enumerate(items, 1)]
+
+
+def describe_recheck(ctx, label: str, article_id: str, message: str, details: dict[str, Any]) -> str:
+    from recala_cli.views import company_timezone, moment_in
+
+    lines = []
+    if details.get("cached") is True:
+        checked_at = details.get("checked_at")
+        when = moment_in(checked_at, company_timezone(ctx, details)) if checked_at else "an unrecorded date"
+        lines.append(f"This text was already checked on {when}; change it to check again.")
+    findings = details["findings"]
+    noun = "finding" if len(findings) == 1 else "findings"
+    lines.append(f"{label}: approval is still blocked. {len(findings)} {noun}:")
+    for finding in findings:
+        # Layout is one numbered line per item; JSON keeps the original diagnostic characters.
+        text = re.sub(r"(?m)^\d+ further unsupported claims\.\s*", "", finding["text"])
+        context, bullet, claim = text.partition("\n- ")
+        if bullet:  # the server's header line rides on the first claim: print it once, above the list
+            lines.append(" ".join(context.split()))
+            text = claim
+        text = text.removeprefix("- ")
+        lines.append(f"{finding['index']}. {' '.join(text.split())}")
+    remaining = re.search(r"(?m)^(\d+) further unsupported claims\.", message)
+    if remaining:
+        lines.append(f"{remaining[1]} more not shown")
+    elif len(message) >= 1500:
+        lines.append("The server cut this list; the article page shows all of them")
+    if "cached" not in details:
+        lines.append("If the text has not changed since its last check, this is that check's saved result.")
+    short_id = article_id[:8]
+    lines.append(f"Change the text, then check again: recala article edit {short_id} --body-file <file> "
+                 f"&& recala article recheck {short_id}")
+    return "\n".join(lines)