recala-cli 0.6.0__py3-none-any.whl

recala_cli/ui.py

@@ -0,0 +1,260 @@
+"""How the CLI looks to a person: the wordmark, the brand palette, spinners, progress and checklists.
+
+Everything here writes to stderr; stdout is only ever the answer. Colour follows
+the terminal: none under NO_COLOR, TERM=dumb or off a TTY, and never in --json
+(those commands do not call this module). Animation also needs a TTY of known width,
+and stops under CI or RECALA_NO_ANIMATION, so logs and agents see one line per event.
+
+The palette is recala.co's: the rust asterisk (#C05621) is the only accent.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+import unicodedata
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import IO, Any
+
+_RESET = "\x1b[0m"
+_RUST_TRUECOLOR = "\x1b[38;2;192;86;33m"  # #C05621, the wordmark's asterisk
+_RUST_256 = "\x1b[38;5;166m"
+_CODES = {"ok": "\x1b[32m", "warn": "\x1b[33m", "err": "\x1b[31m", "dim": "\x1b[2m", "bold": "\x1b[1m"}
+_MARKS = {
+    True: {"done": "✓", "now": "●", "next": "○", "fail": "✗", "skip": "–"},
+    False: {"done": "[x]", "now": "[>]", "next": "[ ]", "fail": "[!]", "skip": "[-]"},
+}
+#: The asterisk pulses while the CLI waits; ASCII terminals get a plain spinner.
+_FRAMES = {True: ("·", "∗", "*", "✳", "✻", "✳", "*", "∗"), False: ("-", "\\", "|", "/")}
+_FRAME_SECONDS = 0.09
+#: Narrower than this, a frame has no room for its label: one line per event instead.
+_MIN_COLUMNS = 8
+
+#: figlet "small" lowercase, unsmushed so every letter stays legible; the accent is added by ``wordmark``.
+_WORDMARK = (
+    r"                    _        ",
+    r" _ _  ___  __  __ _ | | __ _ ",
+    r"| '_|/ -_)/ _|/ _` || |/ _` |",
+    r"|_|  \___|\__|\__,_||_|\__,_|",
+)
+
+
+@dataclass(frozen=True)
+class Style:
+    color: bool
+    animate: bool
+    unicode: bool = True
+    truecolor: bool = False
+
+    @classmethod
+    def for_stream(cls, stream: Any = None) -> Style:
+        stream = sys.stderr if stream is None else stream
+        tty = bool(getattr(stream, "isatty", lambda: False)())
+        dumb = os.environ.get("TERM", "") == "dumb"
+        color = tty and not dumb and "NO_COLOR" not in os.environ
+        animate = tty and not dumb and not os.environ.get("CI") and not os.environ.get("RECALA_NO_ANIMATION")
+        encoding = (getattr(stream, "encoding", None) or os.environ.get("LC_ALL") or os.environ.get("LANG") or "utf-8")
+        return cls(color=color, animate=animate, unicode="utf" in encoding.lower(),
+                   truecolor=os.environ.get("COLORTERM", "") in ("truecolor", "24bit"))
+
+    @classmethod
+    def plain(cls) -> Style:
+        return cls(color=False, animate=False, unicode=False)
+
+    def _paint(self, code: str, text: str) -> str:
+        return f"{code}{text}{_RESET}" if self.color else text
+
+    def accent(self, text: str) -> str:
+        return self._paint(_RUST_TRUECOLOR if self.truecolor else _RUST_256, text)
+
+    def ok(self, text: str) -> str:
+        return self._paint(_CODES["ok"], text)
+
+    def warn(self, text: str) -> str:
+        return self._paint(_CODES["warn"], text)
+
+    def err(self, text: str) -> str:
+        return self._paint(_CODES["err"], text)
+
+    def dim(self, text: str) -> str:
+        return self._paint(_CODES["dim"], text)
+
+    def bold(self, text: str) -> str:
+        return self._paint(_CODES["bold"], text)
+
+    def mark(self, state: str) -> str:
+        symbol = _MARKS[self.unicode][state]
+        painter = {"done": self.ok, "now": self.accent, "fail": self.err}.get(state, self.dim)
+        return painter(symbol)
+
+    def frames(self) -> tuple[str, ...]:
+        return _FRAMES[self.unicode]
+
+    def ellipsis(self) -> str:
+        return "…" if self.unicode else "..."
+
+
+def wordmark(style: Style) -> str:
+    """The recala wordmark with its rust asterisk, as recala.co draws it."""
+    lines = list(_WORDMARK)
+    lines[1] = f"{lines[1]} {style.accent('*')}"
+    return "\n".join(style.bold(line) if index != 1 else line for index, line in enumerate(lines))
+
+
+def banner(subtitle: str, *, style: Style, stream: IO[str] | None = None) -> None:
+    """The wordmark, drawn in with a short sparkle on a live terminal (about a third of a second)."""
+    out = sys.stderr if stream is None else stream
+    out.write("\n" + wordmark(style) + "\n")
+    if style.animate:
+        for frame in style.frames():
+            out.write(f"\r  {style.accent(frame)} {style.dim(subtitle)}")
+            out.flush()
+            time.sleep(0.04)
+        out.write("\r\x1b[K")
+    out.write(f"  {style.accent('*')} {style.dim(subtitle)}\n\n")
+    out.flush()
+
+
+def progress_bar(done: int, total: int, *, width: int = 24, style: Style) -> str:
+    shown = max(0, min(done, total))
+    filled = round(width * shown / total) if total else 0
+    full, empty = ("█", "░") if style.unicode else ("#", "-")
+    return f"[{style.accent(full * filled)}{style.dim(empty * (width - filled))}] {shown}/{total}"
+
+
+def checklist(rows: list[tuple[str, str, str]], *, style: Style) -> str:
+    """One line per step: its mark, number, title and a short detail (``state`` is done, now, next, fail or skip)."""
+    title_width = max((len(title) for title, _, _ in rows), default=0) + 4
+    number_width = len(str(len(rows)))
+    arrow = "← now" if style.unicode else "<- now"
+    lines = []
+    for index, (title, state, detail) in enumerate(rows, start=1):
+        shown = detail or (arrow if state == "now" else "")
+        painted = style.accent(shown) if state == "now" and not detail else style.dim(shown)
+        line = f"  {style.mark(state)}  {index:>{number_width}}  {title:<{title_width}}{painted if shown else ''}"
+        lines.append(line.rstrip())
+    return "\n".join(lines)
+
+
+def cell_width(text: str) -> int:
+    """The columns ``text`` takes on a terminal: wide characters take two, combining marks none."""
+    return sum(_char_width(char) for char in text)
+
+
+def _char_width(char: str) -> int:
+    if unicodedata.combining(char):
+        return 0
+    return 2 if unicodedata.east_asian_width(char) in "WF" else 1
+
+
+def fit(text: str, columns: int, *, ellipsis: str) -> str:
+    """``text`` cut to at most ``columns`` cells, ending in ``ellipsis`` when it had to be cut."""
+    if cell_width(text) <= columns:
+        return text
+    room, kept = columns - cell_width(ellipsis), ""
+    for char in text:
+        if cell_width(kept + char) > room:
+            break
+        kept += char
+    return kept.rstrip() + ellipsis if room >= 0 else ellipsis[:columns]
+
+
+def status_line(frame: str, label: str, elapsed: int, *, columns: int, style: Style) -> str:
+    """One spinner frame that never wraps: a wrapped frame leaves a new line behind on every redraw.
+
+    It stops one column short of the edge (writing the last column makes some terminals wrap),
+    drops the clock before it shortens the label, and shortens the label with an ellipsis.
+    """
+    room = columns - 1
+    lead = f"  {frame} "
+    clock = f" {elapsed}s" if elapsed >= 2 else ""
+    if cell_width(lead + label + clock) > room:
+        clock = ""
+    shown = fit(label, max(room - cell_width(lead), 0), ellipsis=style.ellipsis())
+    return f"  {style.accent(frame)} {shown}{style.dim(clock) if clock else ''}"
+
+
+def terminal_columns(stream: Any) -> int | None:
+    """The width of the terminal behind ``stream``; None off a terminal or when unknown."""
+    try:
+        return os.get_terminal_size(stream.fileno()).columns or None
+    except (AttributeError, OSError, ValueError):
+        return None
+
+
+class Spinner:
+    """A pulsing asterisk with a label while something slow runs; one line per event elsewhere.
+
+    ``columns`` reads the terminal's width, every frame, so a resized window still gets one line;
+    None means unknown, and then nothing animates.
+    """
+
+    def __init__(self, label: str, *, stream: IO[str] | None = None, style: Style | None = None,
+                 columns: Callable[[], int | None] | None = None, tty_only: bool = False) -> None:
+        self.label = label
+        self._tty_only = tty_only  # on a pipe or in a log: no progress lines at all
+        self._stream = sys.stderr if stream is None else stream
+        self._style = style or Style.for_stream(self._stream)
+        self._columns = columns or (lambda: terminal_columns(self._stream))
+        self._animate = False
+        self._finished = False
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._started = time.monotonic()
+
+    def __enter__(self) -> Spinner:
+        self._animate = self._style.animate and (self._columns() or 0) >= _MIN_COLUMNS
+        if self._animate:
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+        elif not self._tty_only:
+            self._write(f"{self.label} ...\n")
+        return self
+
+    def update(self, label: str) -> None:
+        self.label = label
+        if not self._animate and not self._tty_only:
+            self._write(f"{label}\n")
+
+    def done(self, message: str) -> None:
+        self._finish(f"  {self._style.mark('done')} {message}" if self._animate else message)
+
+    def fail(self, message: str) -> None:
+        self._finish(f"  {self._style.mark('fail')} {message}" if self._animate else message)
+
+    def __exit__(self, kind: Any, error: Any, trace: Any) -> None:
+        if not self._finished:
+            if kind is None:
+                self.done(self.label)
+            else:
+                self.fail(f"{self.label}: stopped")
+
+    def _finish(self, line: str) -> None:
+        self._finished = True
+        if self._tty_only and not self._animate:
+            return
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=1)
+            self._write("\r\x1b[K")
+        self._write(f"{line}\n")
+
+    def _spin(self) -> None:
+        frames = self._style.frames()
+        index = 0
+        while not self._stop.is_set():
+            columns = self._columns()
+            if columns is not None and columns >= _MIN_COLUMNS:  # resized too narrow: skip
+                elapsed = int(time.monotonic() - self._started)
+                frame = frames[index % len(frames)]
+                line = status_line(frame, self.label, elapsed, columns=columns, style=self._style)
+                self._write(f"\r\x1b[K{line}")
+            index += 1
+            self._stop.wait(_FRAME_SECONDS)
+
+    def _write(self, text: str) -> None:
+        self._stream.write(text)
+        self._stream.flush()

recala_cli/updates.py

@@ -0,0 +1,43 @@
+"""Best-effort daily notices from the existing public CLI release pointer."""
+
+import json
+import os
+import re
+from datetime import UTC, datetime
+
+import click
+import httpx
+
+from recala_cli import __version__, config
+
+LATEST_URL = "https://recala.co/releases/cli/LATEST"
+UPGRADE = "recala update"
+
+
+def latest_version():
+    response = httpx.get(LATEST_URL, timeout=2, follow_redirects=False)
+    response.raise_for_status()
+    version = response.text.strip()
+    return version if re.fullmatch(r"\d+\.\d+\.\d+", version) else None
+
+
+def notify_update(*, as_json):
+    if as_json or os.environ.get("RECALA_NO_UPDATE_CHECK") == "1":
+        return
+    path = config.config_dir() / "update-check.json"
+    today = datetime.now(UTC).date().isoformat()
+    try:
+        if path.exists() and json.loads(path.read_text()).get("checked_on") == today:
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({"checked_on": today}))
+        latest = latest_version()
+        if latest and tuple(map(int, latest.split("."))) > tuple(
+            map(int, __version__.split("."))
+        ):
+            click.echo(
+                f"Recala {latest} is available (installed {__version__}). Update: {UPGRADE}",
+                err=True,
+            )
+    except (OSError, ValueError, httpx.HTTPError):
+        pass  # Release availability never blocks company work.

recala_cli/views.py

@@ -0,0 +1,372 @@
+"""Human views: what a person reads in the terminal. Pure functions of the API's answers.
+
+--json never comes through here: agents get the answer itself. Each view says what
+the state is and, when something is missing, the one command that fixes it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from datetime import UTC, datetime
+from typing import Any
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import click
+
+from recala_cli import config
+from recala_cli.ui import Style
+
+#: The CLI-facing way to pay: an owner makes a 30-day link for whoever pays (not the web billing page).
+PAY_LINK_STEP = "an owner makes a pay link with recala billing link --plan go (or --plan self_serve)"
+
+
+def pay_link_step() -> str:
+    """PAY_LINK_STEP for the company this command ran on: `recala billing link` acts on the saved active company,
+    so when --org / RECALA_ORG chose another one the hint must say which."""
+    context = click.get_current_context(silent=True)
+    resolved = context.meta.get("resolved_org") if context else None
+    if resolved and resolved != config.saved_active_org():
+        return PAY_LINK_STEP.replace("recala billing link", f"recala billing link --org {resolved}")
+    return PAY_LINK_STEP
+
+#: The engines as the panel names them (src/question_panel/types.py ENGINE_NAMES).
+_ENGINE_NAMES = {"google_organic": "Google", "google_aio": "Google AI Overview", "chatgpt": "ChatGPT", "gemini": "Gemini"}
+_PLAN_NAMES = {"go": "Recala Go", "self_serve": "Self-serve", "managed": "Managed", "free": "No plan yet"}
+_GSC_STATES = {
+    "not_connected": "not connected",
+    "connecting": "signed in; choose the property",
+    "pending_review": "waiting for Recala to confirm the property",
+    "needs_reconnect": "needs you to sign in to Google again",
+    "backfilling": "connected; importing your history",
+    "waiting_for_data": "connected; waiting for Google's first data",
+    "live": "live",
+    "stale": "stale",
+}
+
+
+def _day(value: str | None, zone: str | None = None) -> str:
+    moment = _local(value, zone) if zone else _parse(value)
+    return f"{moment.day} {moment:%b %Y}" if moment else ""
+
+
+def _parse(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _local(value: str | None, zone: str | None) -> datetime | None:
+    moment = _parse(value)
+    if moment is None:
+        return None
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=UTC)
+    try:
+        return moment.astimezone(ZoneInfo(zone or "UTC"))
+    except (ValueError, ZoneInfoNotFoundError):
+        return moment.astimezone(UTC)
+
+
+def local_time(value: str | None, zone: str | None) -> str:
+    """A short company-local instant; the view labels its timezone once."""
+    moment = _local(value, zone)
+    return f"{moment:%a} {moment.day} {moment:%b, %H:%M}" if moment else "date not recorded"
+
+
+_INSTANT = re.compile(r"\d{4}-\d\d-\d\d[T ]\d\d:\d\d(?::\d\d(?:\.\d+)?)?(?:Z|[+-]\d\d:?\d\d)?")
+
+
+def localise_instants(value: Any, zone: str | None) -> tuple[Any, bool]:
+    """A copy of a result with every ISO instant written as the company reads it, and whether any was found.
+
+    Only for human views: --json keeps the API's own strings."""
+    if isinstance(value, str) and _INSTANT.fullmatch(value) and _parse(value) is not None:
+        return local_time(value, zone), True
+    if isinstance(value, dict):
+        converted = {key: localise_instants(item, zone) for key, item in value.items()}
+        return {key: item for key, (item, _) in converted.items()}, any(found for _, found in converted.values())
+    if isinstance(value, list):
+        converted_items = [localise_instants(item, zone) for item in value]
+        return [item for item, _ in converted_items], any(found for _, found in converted_items)
+    return value, False
+
+
+def timezone_label(zone: str | None) -> str:
+    if zone:
+        try:
+            ZoneInfo(zone)
+            return f"({zone})"
+        except (ValueError, ZoneInfoNotFoundError):
+            pass
+    return "(timezone not set; times in UTC)"
+
+
+def company_timezone(ctx, data: dict[str, Any]) -> str | None:
+    """The company's zone, read the way `recala plan` reads it: payload first, then the saved publication cadence,
+    then the company record. One lookup per command; a view that has no zone says so instead of guessing."""
+    zone = ((data.get("org") or {}).get("timezone")
+            or (data.get("cadence") or {}).get("timezone"))
+    if zone:
+        return zone
+    # The calendar API substitutes UTC when the company's timezone is unset.
+    if data.get("timezone") and data["timezone"] != "UTC":
+        return data["timezone"]
+    if "company_zone" in ctx.meta:
+        return ctx.meta["company_zone"]  # type: ignore[no-any-return]
+    ctx.meta["company_zone"] = _read_company_zone(ctx.meta.get("org_client"))
+    return ctx.meta["company_zone"]  # type: ignore[no-any-return]
+
+
+def _read_company_zone(client) -> str | None:
+    from recala_cli.endpoints import CADENCE_SHOW, ORG_SHOW
+    from recala_cli.errors import CliError
+
+    if client is None:
+        return None
+    for read in (lambda: ((client.call(CADENCE_SHOW) or {}).get("cadence") or {}).get("timezone"),
+                 lambda: (client.call(ORG_SHOW, path={"org_id": client.org_id}).get("org") or {}).get("timezone")):
+        try:
+            zone = read()
+        except CliError:
+            continue
+        if zone:
+            return zone  # type: ignore[no-any-return]
+    return None
+
+
+def engine_name(engine: str) -> str:
+    return _ENGINE_NAMES.get(engine, engine.replace("_", " "))
+
+
+def moment_in(value: str | None, zone: str | None) -> str:
+    """'Tue 6 Oct 2026, 09:00 (Europe/Madrid)': a stored instant as the company reads it."""
+    moment = _local(value, zone)
+    return f"{moment:%a} {moment.day} {moment:%b %Y, %H:%M} ({zone or 'UTC'})" if moment else str(value or "")
+
+
+def _count(value: Any) -> str:
+    number = float(value or 0)
+    return f"{number:g}"
+
+
+# ── credits ─────────────────────────────────────────────────────────────────────
+
+
+def credit_lines(summary: dict[str, Any], entitlements: dict[str, Any] | None, managed: dict[str, Any] | None,
+                 *, show_question_cap: bool = True, zone: str | None = None) -> list[str]:
+    """Plan, what is left, caps and the reset date. An internal account is unlimited, never "0 available"."""
+    if summary.get("dogfood") and summary.get("period"):
+        return _dogfood_credit_lines(summary, zone) + _cap_lines(entitlements, show_question_cap=show_question_cap)
+    plan = summary.get("plan")
+    if plan == "internal":
+        return ["Unlimited: no plan caps apply."]
+    if not summary:
+        return ["Credits: unavailable right now; try again in a minute."]
+    if plan == "managed" or (managed or {}).get("managed"):
+        usage = managed or {}
+        period = summary.get("period") or {}
+        cap, used = int(usage.get("cap") or period.get("allowance") or 0), int(usage.get("used") or 0)
+        ends = _day(usage.get("period_end") or period.get("ends_at"), zone)
+        return [f"Managed plan: {used} of {cap} articles used this month" + (f" (resets {ends})" if ends else "")]
+    period = summary.get("period")
+    lines = []
+    if period:
+        label = summary.get("plan_name") or _PLAN_NAMES.get(str(summary.get("plan_key") or plan), str(plan))
+        renews = "renews" if period.get("renews") else "ends"
+        lines.append(f"{label}: {_count(period.get('left'))} of {_count(period.get('allowance'))} articles left this "
+                     f"period ({renews} {_day(period.get('ends_at'), zone)})")
+    else:
+        lines.append(f"No plan yet: {_count(summary.get('free_left'))} free article(s) left. "
+                     f"Human payment: {pay_link_step()}; then recala status")
+    if float(summary.get("extra_left") or 0) > 0:
+        lines.append(f"Extra articles: {_count(summary.get('extra_left'))}")
+    lines.extend(_cap_lines(entitlements, show_question_cap=show_question_cap))
+    return lines
+
+
+def _dogfood_credit_lines(summary: dict[str, Any], zone: str | None = None) -> list[str]:
+    """The allowance and the extras past it, in a customer's words: at no charge, or refused when extras are not included.
+
+    The accounting detail (what it would cost, which limit) stays in --json."""
+    period, comp = summary["period"], summary["dogfood"]
+    label = summary.get("plan_name") or _PLAN_NAMES.get(str(summary.get("plan_key") or summary.get("plan")), "No plan")
+    allowance = period["allowance"]
+    used = period.get("used", allowance - period["left"])
+    lines = [f"{label}: {used} of {allowance} articles used" if used <= allowance
+             else f"{label}: {used} articles this period, {allowance} included in the plan"]
+    if period.get("ends_at"):
+        renews = "renews" if period.get("renews") else "ends"
+        lines[0] += f" ({renews} {_day(period['ends_at'], zone)})"
+    if comp.get("comp_overflow") is False:  # reserve_dogfood_article answers cap_reached past the allowance
+        return lines + [f"Extra articles are not included: articles past the {allowance}-article allowance are refused"]
+    extras = comp.get("extras_priced", comp["extras_used"]) + (comp.get("extras_over_limit") or 0)
+    if extras:
+        priced_only = not comp.get("extras_over_limit")  # past the extras limit the price no longer adds up
+        worth = f" (worth €{comp['would_charge_cents'] / 100:g})" if comp.get("would_charge_cents") and priced_only else ""
+        lines.append(f"Extra articles this period: {extras}, at no charge{worth}")
+    lines.append(f"Your next extra article is at no charge (normally €{comp['extra_price_cents'] / 100:g})")
+    return lines
+
+
+def _cap_lines(entitlements: dict[str, Any] | None, *, show_question_cap: bool = True) -> list[str]:
+    if not entitlements or not entitlements.get("plan"):
+        return []
+    questions, cadences = entitlements.get("questions_tracked") or {}, entitlements.get("cadences") or {}
+    lines = [f"Questions: up to {questions.get('total', 0)} tracked"] if show_question_cap else []
+    if cadences.get("llm_runs_per_week"):
+        lines.append(f"AI answer checks: {cadences['llm_runs_per_week']} a week "
+                     f"({', '.join(engine_name(engine) for engine in cadences.get('llm_engines') or [])})")
+    if entitlements.get("cms_connections"):
+        lines.append(f"CMS connections: {entitlements['cms_connections']}")
+    return lines
+
+
+CARD_PLAN_LABELS = {"go": "Recala Go", "self_serve": "Self-serve"}
+
+
+def describe_pay_link(result: dict[str, Any]) -> str:
+    """`recala billing link`: the URL on its own line, so it can be copied into an email."""
+    plan = CARD_PLAN_LABELS.get(result.get("plan", ""), result.get("plan", ""))
+    return (f"Payment link for {plan} (monthly), valid until {_day(result.get('expires_at'))}:\n{result['url']}\n"
+            "Once it is paid, Recala grants the plan to this company. Anyone with the link can pay it.")
+
+
+def describe_credits(result: dict[str, Any]) -> str:
+    return "\n".join(credit_lines(result.get("summary") or {}, result.get("entitlements"), result.get("managed_usage")))
+
+
+# ── calendar ────────────────────────────────────────────────────────────────────
+
+
+def calendar_view(calendar: dict[str, Any], *, style: Style | None = None,
+                  cadence: dict[str, Any] | None = None) -> str:
+    """Scheduled publications by day: time, title, author and state; then what is ready to book."""
+    if calendar.get("enabled") is False and not calendar.get("slots"):
+        return "Publication calendar: scheduling is not enabled"
+    style = style or Style.plain()
+    from recala_cli.commands.reads import _calendar_candidates, _needs_attention, describe_slot_state
+
+    zone = calendar.get("timezone")
+    cadence = cadence or {}
+    by_article = {c.get("article_id"): c for c in _calendar_candidates(calendar)}
+    days: dict[str, list[str]] = defaultdict(list)
+    for appointment in sorted(calendar.get("appointments") or [], key=lambda a: str(a.get("scheduled_at"))):
+        moment = _local(appointment.get("scheduled_at"), zone)
+        article = by_article.get(appointment.get("article_id")) or {}
+        author = article.get("author_name") or "no author"
+        when = moment.strftime("%H:%M") if moment else "--:--"
+        days[f"{moment:%Y-%m-%d}" if moment else "unknown day"].append(
+            f"  {when}  {article.get('title') or '(untitled article)'}  {style.dim('· ' + author)}  "
+            f"[{describe_slot_state(appointment, cadence)}]")
+    booked_articles = {a.get("article_id") for a in calendar.get("appointments") or []}
+    for slot in calendar.get("slots") or []:
+        if slot.get("article_id") and slot["article_id"] in booked_articles and not _needs_attention(slot):
+            continue
+        moment = _local(slot.get("scheduled_at"), zone)
+        when = moment.strftime("%H:%M") if moment else "--:--"
+        days[f"{moment:%Y-%m-%d}" if moment else "unknown day"].append(
+            f"  {when}  {slot.get('topic') or slot.get('title') or '(no topic)'}  [{describe_slot_state(slot, cadence)}]")
+    lines = [f"Publication calendar {timezone_label(zone)}"]
+    for day, rows in sorted(days.items()):
+        moment = _parse(day)
+        lines.append(style.bold(f"{moment:%a} {moment.day} {moment:%b}" if moment else day))
+        lines.extend(sorted(rows))
+    if not days:
+        lines.append("  Nothing scheduled in this window.")
+    booked = {a.get("article_id") for a in calendar.get("appointments") or []}
+    ready = [c for c in calendar.get("candidates") or [] if c.get("can_schedule") and c.get("article_id") not in booked]
+    if ready:
+        lines.append("Ready to schedule:")
+        lines.extend(f"  {c.get('title')}  ->  recala article schedule {c.get('article_id')} --at <time>" for c in ready)
+    return "\n".join(lines)
+
+
+# ── connections ─────────────────────────────────────────────────────────────────
+
+
+def connection_lines(status: dict[str, Any], *, zone: str | None = None) -> list[str]:
+    """The CMS (its endpoint and the public site articles appear on) and Search Console, each with its next step."""
+    cms, gsc, org = status.get("cms"), status.get("search_console"), status.get("org") or {}
+    public_site = org.get("blog_base_url") or org.get("website_url") or ""
+    lines = ["Publishing (CMS)"]
+    if cms and cms.get("connected"):
+        lines.append(f"  {cms.get('provider')}  connected")
+        sanity = status.get("sanity") or {}
+        if sanity.get("project_id"):
+            lines.append(f"  CMS endpoint:  Sanity project {sanity['project_id']}, dataset {sanity.get('dataset')}")
+        elif cms.get("site_url"):
+            lines.append(f"  CMS endpoint:  {cms['site_url']}")
+        if public_site:
+            lines.append(f"  Public site:   {public_site}")
+        lines.append(f"  Auto-publish:  {'on' if cms.get('auto_publish') else 'off (you approve each article)'}")
+    else:
+        lines.append("  not connected  ->  recala cms connect --provider <sanity|wordpress>")
+    lines.append("Search Console")
+    if gsc is None:
+        lines.append("  switched off on this Recala server")
+    elif gsc.get("state") in (None, "not_connected"):
+        lines.append("  not connected  ->  recala connect gsc")
+    else:
+        lines.append(f"  {_GSC_STATES.get(gsc['state'], gsc['state'])}"
+                     + (f"  ·  {gsc['property']}" if gsc.get("property") else ""))
+        if gsc.get("final_through"):
+            through = gsc["final_through"]
+            lines.append(f"  Data through:  {local_time(through, zone) if 'T' in through else through}")
+        if gsc.get("state") == "connecting":
+            lines.append("  ->  recala connect gsc --property <property>")
+        if gsc.get("state") == "needs_reconnect":
+            lines.append("  ->  recala connect gsc")
+    sitemap = status.get("sitemap")
+    if sitemap:
+        lines.extend(sitemap_lines(sitemap, zone))
+    return lines
+
+
+def sitemap_lines(sitemap: dict[str, Any], zone: str | None = None) -> list[str]:
+    from recala_cli.commands.index import describe_sitemaps
+
+    return ["Sitemaps in Search Console", *describe_sitemaps(sitemap, zone).splitlines()]
+
+
+# ── question panel ──────────────────────────────────────────────────────────────
+
+
+def question_counts(panel: dict[str, Any]) -> tuple[int, int]:
+    """C5 counts when available, otherwise the legacy size and question rows."""
+    count = sum(len(area.get("questions") or []) for area in panel.get("areas") or [])
+    showing, total = panel.get("showing"), panel.get("total")
+    return (showing if showing is not None else count,
+            total if total is not None else panel.get("size", count))
+
+
+def panel_lines(panel: dict[str, Any], entitlements: dict[str, Any] | None = None) -> list[str]:
+    if not panel or not panel.get("enabled"):
+        return ["Questions: the question panel is switched off on this Recala server"]
+    details = panel.get("panel") or {}
+    size = question_counts(details)[1]
+    baseline = panel.get("baseline")
+    run = panel.get("latest_run") or {}
+    if not size and not run:
+        return ["Questions: no baseline yet; Recala starts this for you"]
+    cap = ((entitlements or {}).get("questions_tracked") or {}).get("total")
+    allowance = f" of {cap} allowed" if (entitlements or {}).get("plan") and cap is not None else ""
+    lines = [f"Questions: {size} tracked{allowance}" + (f", baseline {str(run.get('status')).replace('_', ' ')}" if run else "")]
+    for engine, counts in (panel.get("summary") or {}).items():
+        share = counts.get("owned_share")
+        lines.append(f"  {engine_name(engine)}: you own {round(share * 100) if share is not None else 0}% "
+                     "of the answers")
+    if baseline is None and run.get("status") not in ("running", "queued"):
+        lines.append("  Recala starts this for you.")
+    return lines
+
+
+def planned_calendar(calendar, plan):
+    """Overlay the two-week cadence forecast on scheduled publications."""
+    if calendar.get("enabled") is False and not plan.get("slots"):
+        return {**calendar, "slots": []}
+    return {**calendar, "timezone": (plan.get("cadence") or {}).get("timezone") or calendar.get("timezone"),
+            "slots": plan.get("slots") or []}