recala-cli 0.6.0__py3-none-any.whl

recala_cli/commands/auth.py

@@ -0,0 +1,207 @@
+"""`recala login`, `recala logout`, `recala whoami` and `recala grant`."""
+
+from __future__ import annotations
+
+import sys
+from contextlib import AbstractContextManager, nullcontext
+from typing import Any
+
+import click
+
+from recala_cli import auth, config, ui
+from recala_cli.auth import credential_kind
+from recala_cli.client import RecalaClient
+from recala_cli.confirm import GRANT_HOURS, grant_status, is_interactive, record_grant, require_current_signin
+from recala_cli.endpoints import ME, SIGN_OUT
+from recala_cli.display import display_name
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.output import notify
+from recala_cli.organizations import (
+    ORGANIZATION_LOOKUP_FAILED,
+    organization_choices,
+    organization_description,
+    organization_memberships,
+    organization_next_step,
+)
+from recala_cli.runtime import command_runner, common_options, interactive_human_output, json_option, open_client, accepted_yes_option
+
+
+def _describe_sign_in(result: dict[str, Any]) -> str:
+    if not result.get("signed_in"):
+        return "Signed out."
+    who = result.get("email") or result.get("kind", "token")
+    return f"Signed in ({who})."
+
+
+class SignInScreen:
+    """The terminal half of the sign-in: the wordmark, the code, a pulse while the browser half happens."""
+
+    def __init__(self, *, as_json: bool, within_onboarding: bool = False) -> None:
+        self.as_json = as_json
+        self.within_onboarding = within_onboarding  # the journey drew the wordmark already
+        self.style = ui.Style.for_stream()
+
+    def present_code(self, uri: str, code: str) -> None:
+        if self.as_json:  # agents and logs: one plain line, before the JSON answer
+            notify(f"To sign in, open {uri} and enter the code {code}")
+            return
+        if not self.within_onboarding:
+            ui.banner("Sign in to Recala", style=self.style)
+        spaced = " ".join(code)
+        notify(f"  Your code   {self.style.bold(self.style.accent(spaced))}\n")
+        notify(f"  Open {uri} and enter it there.")
+        notify("  New here? Create an account: https://recala.co/register")
+        notify(f"  {self.style.dim('Only approve a code you just requested. Recala never asks for it by email.')}\n")
+
+    def waiting(self) -> AbstractContextManager[Any]:
+        if self.as_json:
+            return nullcontext()
+        return ui.Spinner("Waiting for you to approve the code in your browser", style=self.style)
+
+    def signed_in(self, email: str | None) -> None:
+        if self.as_json:
+            return
+        if self.within_onboarding:
+            notify(f"\n  {self.style.accent('*')} {self.style.bold('Signed in')} as {display_name(email) or 'you'}\n")
+
+
+def _describe_login(ctx: click.Context, result: dict[str, Any]) -> str:
+    if ctx.params.get("with_token") and not interactive_human_output(ctx):
+        return _describe_sign_in(result)
+    me = ctx.meta.get("login_identity") or {}
+    user = me.get("user") if isinstance(me.get("user"), dict) else {}
+    name = display_name(user.get("name") or user.get("display_name") or user.get("email") or result.get("email"))
+    lines = [f"Signed in as {name or result.get('kind') or 'you'}."]
+    if "login_identity" not in ctx.meta:
+        return "\n".join([*lines, ORGANIZATION_LOOKUP_FAILED])
+    rows = me.get("memberships") or []
+    if len(rows) == 1:
+        lines.extend([f"Using {display_name(rows[0].get('name')) or rows[0]['org_id']}.", "Next: recala plan"])
+    else:
+        lines.extend([organization_choices(rows), organization_next_step(rows)])
+    return "\n".join(lines)
+
+
+def _login_next_step(ctx: click.Context) -> None:
+    try:
+        client = RecalaClient(ctx.obj["api_url"], transport=ctx.obj.get("transport"))
+        client.token = auth.bearer_token(client)
+        me = client.call(ME)
+        rows = organization_memberships(me, skip_invalid=True)
+    except (CliError, ValueError):
+        return  # successful sign-in stays successful during a presentation outage
+    ctx.meta["login_identity"] = {**me, "memberships": rows}
+    if len(rows) == 1:
+        config.set_active_org(rows[0]["org_id"])
+
+
+@click.command()
+@json_option
+@command_runner(contextual_human=_describe_login)
+@click.option("--with-token", is_flag=True, help="Read an API key or access token from standard input (for agents and CI).")
+@click.option("--no-browser", is_flag=True, help="Print the sign-in link without opening a browser.")
+def login(ctx: click.Context, with_token: bool, no_browser: bool) -> dict[str, Any]:
+    """Sign in with a one-time code in the browser.
+
+    No account yet? Create one at https://recala.co/register. Agents and CI
+    pipe a key with --with-token."""
+    if with_token:
+        result = auth.store_pasted_token(sys.stdin.readline())
+    else:
+        result = sign_in(ctx, no_browser=no_browser)
+    if not ctx.obj.get("as_json") and (not with_token or interactive_human_output(ctx)):
+        _login_next_step(ctx)
+    return result
+
+
+def sign_in(ctx: click.Context, *, no_browser: bool = False, within_onboarding: bool = False) -> dict[str, Any]:
+    seams = ctx.find_root().obj
+    screen = SignInScreen(as_json=bool(seams.get("as_json")), within_onboarding=within_onboarding)
+    client = RecalaClient(seams["api_url"], transport=seams.get("transport"))
+    result = auth.device_login(
+        client,
+        sleep=seams["sleep"],
+        open_browser=None if no_browser else seams["open_browser"],
+        present_code=screen.present_code,
+        waiting=screen.waiting,
+    )
+    screen.signed_in(result.get("email"))
+    return result
+
+
+@click.command()
+@json_option
+@command_runner(human=_describe_sign_in)
+@accepted_yes_option
+def logout(ctx: click.Context) -> dict[str, Any]:
+    """End this machine's session and forget it here.
+
+    An API key stays valid until revoked."""
+    stored = config.load_credentials()
+    server_revoked = False
+    if stored.get("kind") == "session" and stored.get("access_token"):
+        client = RecalaClient(ctx.obj["api_url"], transport=ctx.obj.get("transport"))
+        client.token = str(stored["access_token"])
+        try:
+            client.call(SIGN_OUT)
+            server_revoked = True
+        except CliError:
+            server_revoked = False  # forgetting it here is still what the person asked for
+    config.forget_credentials()
+    return {"signed_in": False, "server_revoked": server_revoked}
+
+
+def _describe_identity(result: dict[str, Any]) -> str:
+    lines = [f"{result['user'].get('email') or result['user'].get('id')} ({result['credential']})"]
+    active = result.get("active_org")
+    rows = result["memberships"]
+    if active:
+        selected = next((row for row in rows if row["org_id"] == active), {"org_id": active})
+        lines.append(f"Active company: {organization_description(selected)} [{active[:8]}]")
+    else:
+        lines.extend(["No company selected. Visible companies:", organization_choices(rows),
+                      organization_next_step(rows)])
+    lines.append(f"{len(result['memberships'])} company(ies): recala company list")
+    return "\n".join(lines)
+
+
+@click.command()
+@common_options
+@command_runner(human=_describe_identity)
+def whoami(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Who this credential is and what it may act on.
+
+    Its companies, and the active one."""
+    client = open_client(ctx, org_flag, require_org=False)
+    me: dict[str, Any] = client.call(ME)
+    return {**me, "credential": credential_kind(), "active_org": ctx.meta.get("resolved_org")}
+
+
+def _describe_grant(result: dict[str, Any]) -> str:
+    if not result.get("active"):
+        return "Every write asks you first ([y]es / [n]o / [a]ll)."
+    return f"Writes are confirmed for this sign-in until logout or {GRANT_HOURS} hours. Undo: recala grant --revoke"
+
+
+@click.command()
+@json_option
+@command_runner(human=_describe_grant)
+@click.option("--status", "show_status", is_flag=True, help="Show whether writes are confirmed for this sign-in.")
+@click.option("--revoke", is_flag=True, help="Ask before every write again.")
+def grant(ctx: click.Context, show_status: bool, revoke: bool) -> dict[str, Any]:
+    """Confirm every write for this sign-in at once.
+
+    The [a]ll answer, so an agent can work without prompts."""
+    if revoke:
+        config.forget_grant()
+        return grant_status()
+    if show_status:
+        return grant_status()
+    require_current_signin()
+    if not is_interactive(ctx):
+        raise CliError(ExitCode.CONFIRMATION_REQUIRED, "confirmation_required",
+                       "Only you can give this permission: run `recala grant` in a terminal.")
+    if not click.confirm(f"  Let writes run without asking, for this sign-in only (until logout or {GRANT_HOURS} hours)?",
+                         default=False, err=True):
+        raise CliError(ExitCode.CONFIRMATION_REQUIRED, "declined", "Nothing changed: every write still asks you.")
+    return record_grant()

recala_cli/commands/billing.py

@@ -0,0 +1,76 @@
+"""`recala billing`: payments for the company's plan."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from datetime import datetime, timezone
+
+from recala_cli import config
+from recala_cli.commands.refusals import refusals_in_words
+from recala_cli.endpoints import BILLING_INVOICES, BILLING_PAY_LINK
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, accepted_yes_option, dry_run_option
+from recala_cli.views import CARD_PLAN_LABELS, describe_pay_link
+
+INVOICE_STATUSES = {"paid": "paid", "open": "waiting for payment", "draft": "not issued yet", "void": "cancelled",
+                    "uncollectible": "could not be collected"}
+NO_INVOICES_FEATURE = "Invoices are not switched on for this company yet. Your billing page in the portal has them."
+
+
+@click.group()
+def billing() -> None:
+    """Payments for the company's plan (owners)."""
+
+
+def money(cents: int, currency: str) -> str:
+    return f"{cents / 100:,.2f} {currency.upper()}"
+
+
+def describe_invoices(result: dict[str, Any]) -> str:
+    portal = f"{config.web_url()}/portal/billing"
+    invoices = result.get("invoices") or []
+    if not invoices:
+        return f"No invoices yet.\nPayment method and plan changes: {portal}"
+    lines = [f"{len(invoices)} most recent invoice{'' if len(invoices) == 1 else 's'}, newest first:"]
+    for invoice in invoices:
+        day = datetime.fromtimestamp(int(invoice["created"]), tz=timezone.utc).strftime("%d %b %Y").lstrip("0")
+        status = INVOICE_STATUSES.get(invoice.get("status") or "", str(invoice.get("status") or "unknown"))
+        lines.append(f"  {day}  {money(invoice['total'], invoice['currency'])}  {status}"
+                     + (f"  #{invoice['number']}" if invoice.get("number") else ""))
+        if invoice.get("url") and invoice.get("status") != "paid":
+            lines.append(f"    {invoice['url']}")
+    lines.append(f"Payment method and plan changes: {portal}")
+    return "\n".join(lines)
+
+
+@billing.command("invoices")
+@common_options
+@command_runner(human=describe_invoices)
+def invoices(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """The company's recent invoices: date, amount and status (owners).
+
+    Payment method and plan changes happen in the portal; the last line links to it."""
+    with refusals_in_words(not_found=NO_INVOICES_FEATURE):
+        listed: dict[str, Any] = open_client(ctx, org_flag).call(BILLING_INVOICES)
+    return listed
+
+
+@billing.command("link")
+@common_options
+@command_runner(human=describe_pay_link)
+@click.option("--plan", "plan_key", type=click.Choice(tuple(CARD_PLAN_LABELS)), required=True, help="The monthly plan to sell.")
+@click.option("--email", default=None, help="Billing email for receipts (else the current one; yours for a new customer).")
+@accepted_yes_option
+@dry_run_option
+def pay_link(ctx: click.Context, org_flag: str | None, plan_key: str, email: str | None) -> dict[str, Any]:
+    """A 30-day payment link for whoever pays.
+
+    Email it to the payer; once paid, the plan is granted with no manual step.
+    """
+    client = open_client(ctx, org_flag)
+    confirm(ctx, client, f"Create a payment link for {CARD_PLAN_LABELS[plan_key]} (monthly)? Anyone with it can pay it.")
+    body: dict[str, Any] = {"plan": plan_key, **({"email": email} if email else {})}
+    link: dict[str, Any] = client.call(BILLING_PAY_LINK, json=body)
+    return link

recala_cli/commands/bing.py

@@ -0,0 +1,164 @@
+"""Bing Webmaster Tools: connect through the portal's sign-in, choose the site, read the stored numbers.
+
+The numbers come from what Recala has stored, never from a live call to Bing, so exploring them costs nothing.
+Queries and pages are weekly figures and the totals are daily, so they are shown apart and never added together.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli import config
+from recala_cli.client import RecalaClient
+from recala_cli.commands.connect import connect
+from recala_cli.endpoints import BING_PERFORMANCE, BING_SITE, BING_SITES, BING_STATUS, Endpoint
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.polling import BROWSER_POLL_SECONDS, open_in_browser, poll_until
+from recala_cli.prompts import choose
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, optional_read, accepted_yes_option, dry_run_option
+from recala_cli.search_numbers import ranked_lines, totals_sentence
+
+SIGN_IN_WAIT_SECONDS = 600
+NOT_CONNECTED = "Bing Webmaster Tools isn't connected for this company. Connect it: recala connect bing"
+SWITCHED_OFF = "Bing Webmaster Tools isn't switched on for this company yet."
+_NEEDS_SIGN_IN = ("not_connected", "needs_reconnect", None)
+_STATE_SENTENCES = {
+    "connecting": "Signed in to Microsoft. Choose the site: recala bing use",
+    "needs_reconnect": "{site}: Bing access was lost. Reconnect: recala connect bing",
+    "backfilling": "{site}: first import running.",
+    "import_retrying": "{site}: the first import failed and will retry. Bing said: {last_error}",
+    "waiting_for_data": "{site}: connected, and Bing has no search data for it yet.",
+    "live": "{site}: live, data through {data_through}.",
+    "stale": "{site}: updates stopped on {stale_since}.",
+}
+
+
+def describe_status(status: dict[str, Any]) -> str:
+    site = (status.get("property") or "").removeprefix("https://").removeprefix("http://").rstrip("/")
+    template = _STATE_SENTENCES.get(status.get("state") or "", NOT_CONNECTED)
+    return template.format(**{**status, "site": site})
+
+
+def _call(client: RecalaClient, endpoint: Endpoint, **request: Any) -> Any:
+    """A Bing route's refusals, in words: off the rollout (404) or not connected (409)."""
+    try:
+        return client.call(endpoint, **request)
+    except CliError as error:
+        if error.exit_code == ExitCode.NOT_FOUND:
+            raise CliError(ExitCode.NOT_FOUND, "bing_unavailable", SWITCHED_OFF, 404) from error
+        if error.exit_code == ExitCode.CONFLICT:
+            raise CliError(ExitCode.CONFLICT, "bing_not_connected", NOT_CONNECTED, 409) from error
+        raise
+
+
+def _read_status(client: RecalaClient) -> dict[str, Any]:
+    status: dict[str, Any] | None = optional_read(client, BING_STATUS)
+    if status is None:
+        raise CliError(ExitCode.NOT_FOUND, "bing_unavailable", SWITCHED_OFF, 404)
+    return status
+
+
+def _choose_site(ctx: click.Context, client: RecalaClient, site: str | None) -> dict[str, Any]:
+    listed = _call(client, BING_SITES) or {}
+    sites = [entry["site_url"] for entry in listed.get("sites") or []]
+    if not sites:
+        raise CliError(ExitCode.CONFLICT, "no_sites",
+                       "This Microsoft account has no verified site in Bing Webmaster Tools. Verify the site there, "
+                       "or import it from Search Console, then run: recala connect bing. "
+                       "Wrong Microsoft account? Disconnect on the Settings page, then connect again.")
+    chosen = choose(ctx, [(url, url) for url in sites], label="Which site is this company's?", flag="--site", value=site,
+                    default=listed.get("suggested_site"))
+    confirm(ctx, client, f"Use the Bing site {chosen}?")
+    _call(client, BING_SITE, json={"site_url": chosen})
+    return _read_status(client)
+
+
+@connect.command("bing")
+@common_options
+@command_runner(human=describe_status)
+@click.option("--site", default=None, help="The site to use, as listed by: recala bing sites.")
+@accepted_yes_option
+@dry_run_option
+def connect_bing(ctx: click.Context, org_flag: str | None, site: str | None) -> dict[str, Any]:
+    """Connect Bing Webmaster Tools.
+
+    Microsoft sign-in in the browser, then choose the site."""
+    client = open_client(ctx, org_flag)
+    current = _read_status(client)
+    if current.get("state") in _NEEDS_SIGN_IN:
+        open_in_browser(ctx, f"{config.web_url()}/portal/settings?org={client.org_id}",
+                        why="In your browser, press Connect on the Bing Webmaster Tools card and approve Recala:")
+        current = poll_until(ctx, lambda: _read_status(client), lambda s: s.get("state") not in _NEEDS_SIGN_IN,
+                             label="Waiting for the Microsoft sign-in in your browser",
+                             timeout_seconds=SIGN_IN_WAIT_SECONDS, interval_seconds=BROWSER_POLL_SECONDS,
+                             outside_ticks=False, done=lambda s: "Microsoft account connected")
+    if current.get("state") == "connecting" or (site and site != current.get("property")):
+        current = _choose_site(ctx, client, site)
+    return current
+
+
+@click.group()
+def bing() -> None:
+    """Bing Webmaster Tools: its status, sites and search numbers."""
+
+
+@bing.command("status")
+@common_options
+@command_runner(human=describe_status)
+def status(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Whether Bing is connected, and how fresh its numbers are."""
+    return _read_status(open_client(ctx, org_flag))
+
+
+def _describe_sites(listed: dict[str, Any]) -> str:
+    suggested = listed.get("suggested_site")
+    sites = [entry["site_url"] for entry in listed.get("sites") or []]
+    ordered = sorted(sites, key=lambda url: url != suggested)
+    return "\n".join(f"{url}  (suggested)" if url == suggested else url for url in ordered) or "No verified sites."
+
+
+@bing.command("sites")
+@common_options
+@command_runner(human=_describe_sites)
+def sites(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """The sites the connected Microsoft account has verified."""
+    listed: dict[str, Any] = _call(open_client(ctx, org_flag), BING_SITES)
+    return listed
+
+
+@bing.command("use")
+@common_options
+@command_runner(human=describe_status)
+@click.argument("site", required=False)
+@accepted_yes_option
+@dry_run_option
+def use(ctx: click.Context, org_flag: str | None, site: str | None) -> dict[str, Any]:
+    """Choose which verified site is this company's."""
+    return _choose_site(ctx, open_client(ctx, org_flag), site)
+
+
+def _describe_performance(data: dict[str, Any]) -> str:
+    period = data.get("period") or {}
+    heading = f"{data.get('property')}, {period.get('start')} to {period.get('end')}"
+    totals = data.get("totals")
+    if not totals:
+        return f"{heading}\nNo Bing numbers stored for this period yet."
+    if not totals.get("impressions"):  # days Bing reported empty: no search data, never a zero
+        return f"{heading}\nBing has no search data for this site in this period yet."
+    lines = [heading, f"{totals_sentence(totals)}. Data through {data.get('data_through')}."]
+    ranked = ranked_lines("Top queries", data.get("queries") or []) + ranked_lines("Top pages", data.get("pages") or [])
+    if ranked:
+        lines += ["Weekly figures below, separate from the daily totals above.", *ranked]
+    return "\n".join(lines)
+
+
+@bing.command("data")
+@common_options
+@command_runner(human=_describe_performance)
+@click.option("--days", type=click.IntRange(7, 90), default=28, show_default=True, help="How many days back to read.")
+def data(ctx: click.Context, org_flag: str | None, days: int) -> dict[str, Any]:
+    """The stored search numbers: totals, top queries and top pages."""
+    answer: dict[str, Any] = _call(open_client(ctx, org_flag), BING_PERFORMANCE, params={"window_days": days})
+    return answer

recala_cli/commands/cadence.py

@@ -0,0 +1,217 @@
+"""Publication cadence, owner consent and a read-only two-week plan."""
+
+from datetime import time
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import click
+
+from recala_cli.ids import resolve_person_id
+from recala_cli.commands.faithful_translations import faithful_translations
+from recala_cli.commands.reads import describe_slot_state
+from recala_cli.endpoints import (
+    AUTOAPPROVE_SET,
+    AUTOAPPROVE_SHOW,
+    CADENCE_SET,
+    CADENCE_SHOW,
+    PUBLICATION_PLAN,
+)
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, optional_read, accepted_yes_option
+from recala_cli.labels import resource_label
+from recala_cli.errors import CliError
+from recala_cli.organizations import organization_label
+
+DAYS = ("mon", "tue", "wed", "thu", "fri", "sat", "sun")
+
+
+CADENCE_FIELDS = ("days", "local_time", "timezone", "autopilot_enabled", "write_ahead_hours", "daily_generation_cap")
+
+
+def current_cadence(client):
+    """The saved settings a change leaves alone, so a preview describes the result and not just the request."""
+    saved = (optional_read(client, CADENCE_SHOW) or {}).get("cadence") or {}
+    return {field: saved[field] for field in CADENCE_FIELDS if saved.get(field) is not None}
+
+
+def show_cadence(result):
+    data = result.get("cadence") or {}
+    if not data:
+        return "No publication cadence configured."
+    days = ",".join(DAYS[day] for day in data["days"])
+    consent = "on" if data.get("autopilot_enabled") else "off"
+    prefix = "Dry run — " if result.get("dry_run") else ""
+    return f"{prefix}{days} at {data['local_time']} {data['timezone']} · autopilot={consent}"
+
+
+def describe_company_cadence(ctx, result):
+    company = ctx.meta.get("cadence_company")
+    return (f"{company}\n" if company else "") + show_cadence(result)
+
+
+@click.group()
+def cadence():
+    """Show or set publication days and time.
+
+    Changing them needs an owner session."""
+
+
+@cadence.command("show")
+@common_options
+@command_runner(contextual_human=describe_company_cadence)
+def show(ctx, org_flag):
+    """Show the publication days, time and autopilot setting."""
+    client = open_client(ctx, org_flag)
+    ctx.meta["cadence_company"] = organization_label(ctx, client)
+    return client.call(CADENCE_SHOW)
+
+
+@cadence.command("set")
+@common_options
+@command_runner(contextual_human=describe_company_cadence)
+@click.option("--days", required=True, help="Comma-separated weekdays: mon,wed,fri.")
+@click.option("--time", "local_time", required=True)
+@click.option("--tz", "timezone", required=True)
+@click.option(
+    "--autopilot/--no-autopilot",
+    default=None,
+    help="Opt into topic assignment and generation; preserves current consent if omitted.",
+)
+@click.option("--ahead-hours", type=click.IntRange(36, 336), default=None)
+@click.option("--daily-cap", type=click.IntRange(1, 10), default=None)
+@click.option(
+    "--dry-run", is_flag=True, help="Validate and print proposed settings without saving."
+)
+@accepted_yes_option
+def set_cadence(
+    ctx, org_flag, days, local_time, timezone, autopilot, ahead_hours, daily_cap, dry_run
+):
+    """Set publication days and time; --dry-run previews without saving."""
+    try:
+        parsed_days = sorted({DAYS.index(day.strip().lower()) for day in days.split(",")})
+        clock = time.fromisoformat(local_time)
+        if clock.tzinfo or clock.second or clock.microsecond:
+            raise ValueError()
+        ZoneInfo(timezone)
+    except (ValueError, ZoneInfoNotFoundError) as error:
+        raise click.BadParameter("Use mon..sun, HH:MM and a valid IANA timezone.") from error
+    body = {"days": parsed_days, "local_time": clock.strftime("%H:%M"), "timezone": timezone}
+    for key, value in (
+        ("autopilot_enabled", autopilot),
+        ("write_ahead_hours", ahead_hours),
+        ("daily_generation_cap", daily_cap),
+    ):
+        if value is not None:
+            body[key] = value
+    client = open_client(ctx, org_flag)
+    if dry_run:
+        return {"dry_run": True, "cadence": {**current_cadence(client), **body}}
+    ctx.meta["cadence_company"] = organization_label(ctx, client)
+    policy = {}
+    if not ctx.obj.get("as_json"):
+        try:
+            policy = optional_read(client, AUTOAPPROVE_SHOW) or {}
+        except CliError:
+            pass  # A missing display name must not bypass or prevent consent.
+
+    describe_signer(ctx, client, policy.get("default_author_person_id"))
+    signer = ctx.meta.get("author_label") or "the configured signer"
+    confirm(ctx, client, f"Save publication cadence ({body['timezone']}, {body['local_time']}) with {signer}?"
+            + (" Enable autopilot?" if autopilot else ""))
+    return client.call(CADENCE_SET, json=body)
+
+
+@click.group()
+def autoapprove():
+    """Automatic acceptance of passing drafts.
+
+    Changing it needs an owner session."""
+
+
+autoapprove.add_command(faithful_translations)
+
+
+def show_policy(ctx, data):
+    consent = "on" if data.get("auto_approve_passing") or data.get("enabled") else "off"
+    author = ctx.meta.get("author_label") or data.get("default_author_person_id") or "not configured"
+    prefix = "Dry run — " if data.get("dry_run") else ""
+    return f"{prefix}Auto-approve: {consent} · author: {author}"
+
+
+@autoapprove.command("show")
+@common_options
+@command_runner(contextual_human=show_policy)
+def show_approval(ctx, org_flag):
+    """Show whether passing drafts are auto-approved."""
+    client = open_client(ctx, org_flag)
+    policy = client.call(AUTOAPPROVE_SHOW)
+    describe_signer(ctx, client, policy.get("default_author_person_id"))
+    return policy
+
+
+def describe_signer(ctx, client, author):
+    if author:
+        ctx.meta["author_label"] = resource_label(ctx, client, "person", author, result_subject=False)
+
+
+def change_approval(ctx, org_flag, enabled, author, dry_run):
+    client = open_client(ctx, org_flag)
+    author = resolve_person_id(client, author) if author else author
+    policy = client.call(AUTOAPPROVE_SHOW)
+    body = {
+        "enabled": enabled,
+        "default_author_person_id": author or policy.get("default_author_person_id"),
+    }
+    describe_signer(ctx, client, body["default_author_person_id"])
+    if dry_run:
+        return {"dry_run": True, **body}
+    signer = ctx.meta.get("author_label") or "the configured signer"
+    confirm(ctx, client, f"Turn auto-approve {'on' if enabled else 'off'}, signed by {signer}?")
+    return client.call(AUTOAPPROVE_SET, json=body)
+
+
+@autoapprove.command("on")
+@common_options
+@command_runner(contextual_human=show_policy)
+@click.option(
+    "--author", default=None, help="Active signing person's id; otherwise keep the current author."
+)
+@click.option("--dry-run", is_flag=True)
+@accepted_yes_option
+def on(ctx, org_flag, author, dry_run):
+    """Turn on automatic approval for this organization."""
+    return change_approval(ctx, org_flag, True, author, dry_run)
+
+
+@autoapprove.command("off")
+@common_options
+@command_runner(contextual_human=show_policy)
+@click.option("--dry-run", is_flag=True)
+@accepted_yes_option
+def off(ctx, org_flag, dry_run):
+    """Turn off automatic approval for this organization."""
+    return change_approval(ctx, org_flag, False, None, dry_run)
+
+
+def describe_plan(result):
+    from recala_cli.views import moment_in
+    cadence = result.get("cadence") or {}
+    zone = cadence.get("timezone") or result.get("timezone") or "UTC"
+    lines = ["Dry run — no changes"]
+    for slot in result.get("slots") or []:
+        lines.append(
+            f"{moment_in(slot.get('scheduled_at'), zone)}  "
+            f"{slot.get('topic') or slot.get('title') or '(no topic)'}  · "
+            f"{describe_slot_state(slot, cadence)}"
+        )
+    lines.extend(f"{topic['topic']} -> skipped -> {topic['reason']}" for topic in result.get("skipped_topics", []))
+    return "\n".join(lines)
+
+
+@click.command()
+@common_options
+@command_runner(human=describe_plan)
+@click.option("--weeks", type=click.IntRange(1, 2), default=2, show_default=True)
+def plan(ctx, org_flag, weeks):
+    """Preview each slot, topic and state.
+
+    Never generates, approves or publishes."""
+    return open_client(ctx, org_flag).call(PUBLICATION_PLAN, params={"weeks": weeks})