reviso-cli 0.1.0__py3-none-any.whl

reviso_cli/__init__.py

@@ -0,0 +1,8 @@
+"""Reviso command line client."""
+from __future__ import annotations
+
+from .client import RevisoClient
+
+__version__ = "0.1.0"
+
+__all__ = ["RevisoClient", "__version__"]

reviso_cli/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

reviso_cli/access.py

@@ -0,0 +1,49 @@
+"""Access levels used by invites and share links.
+
+The three levels below are the vocabulary a user types and sees. What each level
+resolves to on the server is deliberately not represented here: the server owns
+that mapping, and the client sends the level, not an expanded result.
+"""
+from __future__ import annotations
+
+ACCESS_TO_ROLE = {
+    "view": "viewer",
+    "comment": "commenter",
+    "edit": "editor",
+}
+
+VALID_ACCESS = tuple(ACCESS_TO_ROLE)
+
+
+def normalize_access(access: str) -> str:
+    value = str(access or "comment").strip()
+    if value not in ACCESS_TO_ROLE:
+        raise ValueError("access must be view, comment, or edit")
+    return value
+
+
+def role_for_access(access: str) -> str:
+    return ACCESS_TO_ROLE[normalize_access(access)]
+
+
+def access_from_body(body: dict) -> str:
+    if str(body.get("role", "")).strip():
+        raise ValueError("role is no longer accepted; pass access")
+    return normalize_access(str(body.get("access") or "comment"))
+
+
+def invite_access_from_body(body: dict) -> str:
+    return access_from_body(body)
+
+
+def invite_for_public(item: dict) -> dict:
+    result = {key: value for key, value in item.items() if key != "role"}
+    result["access"] = normalize_access(str(item.get("access") or "comment"))
+    return result
+
+
+def invite_list_for_public(result: dict) -> dict:
+    return {
+        **result,
+        "invites": [invite_for_public(item) for item in result.get("invites", [])],
+    }

reviso_cli/cli/__init__.py

@@ -0,0 +1,276 @@
+"""Command line dispatcher. Every server call goes through RevisoClient."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+from .. import command_journal
+from ..client import RevisoClient
+from ..document_route_keys import public_document_path
+from ..document_search import search_documents
+from ..errors import ValidationError
+from ..local import read_mapping, write_mapping  # noqa: F401
+from ..origin import DEFAULT_SERVER_URL
+from ..paths import config_path, packet_path, read_json, write_json
+from ..scope import resolve_agent_create_scope
+from .doctor import doctor_report, print_doctor
+from .guest_comments import add_guest_comment_commands
+from .invites import add_invite_commands
+from .versions import add_version_commands, format_file_arg
+
+# Response blocks that are browser UI state. The human status line drops them;
+# --json keeps them.
+ACCESS_KEYS = ("effective_access", "security_policy")
+
+
+def _load_config() -> dict:
+    path = config_path()
+    if path.exists():
+        return read_json(path)
+    return {}
+
+
+def _server_url() -> str:
+    cfg = _load_config()
+    return os.environ.get("REVISO_SERVER",
+                          cfg.get("server", DEFAULT_SERVER_URL))
+
+
+def _automation_key(cfg: dict) -> str:
+    return (os.environ.get("REVISO_AUTOMATION_KEY")
+            or cfg.get("automation_key", ""))
+
+
+def _client() -> RevisoClient:
+    return RevisoClient(_server_url(), _automation_key(_load_config()) or None)
+
+
+def cmd_auth(args: argparse.Namespace) -> None:
+    if args.action == "login":
+        key = args.key or os.environ.get("REVISO_AUTOMATION_KEY", "")
+        server = args.server or os.environ.get("REVISO_SERVER",
+                                               DEFAULT_SERVER_URL)
+        if not key:
+            print("No automation key. Create one in Reviso under Settings -> "
+                  "Integrations, then set REVISO_AUTOMATION_KEY or pass --key.")
+            return
+        write_json(config_path(), {"server": server, "automation_key": key})
+        print(f"Saved to {config_path()}")
+    elif args.action == "status":
+        cfg = _load_config()
+        print(f"server: {cfg.get('server', '(not set)')}")
+        print(f"key: {'set' if cfg.get('automation_key') else '(not set)'}")
+        print(f"config: {config_path()}")
+    else:
+        print(f"unknown auth action: {args.action}")
+
+
+def cmd_publish(args: argparse.Namespace) -> None:
+    path = Path(args.file)
+    scope = _workspace_scope(args.workspace_id or "", args.parent_id or "")
+    content = path.read_text()
+    fmt = format_file_arg(args, path)
+    title = args.title or path.name
+    # A journaled operation_id is reused across reruns of THIS command, so a
+    # crashed-then-rerun publish replays instead of double-creating. Cleared
+    # only after every local success step has completed.
+    parts = [title, content, fmt, args.description or "",
+             scope.workspace_id, scope.parent_id]
+    op = command_journal.operation_id_for("publish", parts)
+    result = _client().publish(title, content, fmt, args.description,
+                               scope.workspace_id, scope.parent_id,
+                               operation_id=op)
+    mapping = write_mapping(result, path)
+    print(mapping["url"])
+    command_journal.forget("publish", parts)
+
+
+def cmd_open(args: argparse.Namespace) -> None:
+    print(f"{_server_url()}{public_document_path(args.document_id)}")
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    payload = _client().status(args.document_id)
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    for key, value in payload.items():
+        if key in ACCESS_KEYS:
+            continue
+        print(f"{key}: {value}")
+
+
+def cmd_server_info(args: argparse.Namespace) -> None:
+    client = _client()
+    payload = {"health": client.health,
+               "ready": client.ready,
+               "version": client.version_info}[args.kind]()
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+def cmd_workspaces(args: argparse.Namespace) -> None:
+    payload = _client().workspaces()
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    for ws in payload.get("workspaces", []):
+        print(f"{ws.get('workspace_id')}\t{ws.get('workspace_name')}\t"
+              f"[{ws.get('workspace_type')}]\t{ws.get('role')}")
+
+
+def cmd_documents(args: argparse.Namespace) -> None:
+    payload = _client().dashboard(args.workspace_id or "")
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    for doc in payload.get("reviews", []):
+        status = doc.get("lifecycle_status") or ""
+        print(f"{doc.get('document_id')}\t{doc.get('title')}\t"
+              f"[{status}]\t{doc.get('unresolved_count')} open")
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    try:
+        payload = search_documents(
+            _client(), args.query, workspace_id=args.workspace_id or "",
+            limit=args.limit, archived=args.archived,
+            include_content=args.include_content)
+    except ValidationError as exc:
+        raise SystemExit(str(exc)) from exc
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    for doc in payload.get("matches", []):
+        print(f"{doc.get('document_id')}\t{doc.get('title')}\t"
+              f"[{doc.get('match_field')}]\t{doc.get('snippet')}")
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    cfg = _load_config()
+    report = doctor_report(
+        _client(), _server_url(), _automation_key(cfg),
+        os.environ.get("REVISO_WORKSPACE_ID", cfg.get("workspace_id", "")))
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True))
+        return
+    print_doctor(report)
+
+
+def cmd_packet(args: argparse.Namespace) -> None:
+    v = "2" if args.v2 else "3"
+    packet = _client().packet(args.document_id, args.thread_id, version=v)
+    pid = packet.get("document_id", args.document_id)
+    path = packet_path(f"pkt_{pid}", "json")
+    write_json(path, packet)
+    print(str(path))
+
+
+def _workspace_scope(explicit: str = "", parent_id: str = ""):
+    cfg = _load_config()
+    key = _automation_key(cfg)
+    return resolve_agent_create_scope(
+        explicit_workspace_id=explicit, explicit_parent_id=parent_id,
+        config=cfg, has_automation_key=key.startswith("rak_"))
+
+
+def _add_basic(sub: argparse._SubParsersAction) -> None:
+    auth = sub.add_parser("auth")
+    auth.add_argument("action", nargs="?", default="login")
+    auth.add_argument("--server")
+    auth.add_argument("--key")
+    auth.set_defaults(func=cmd_auth)
+    pub = sub.add_parser("publish")
+    pub.add_argument("file")
+    pub.add_argument("--title")
+    pub.add_argument("--format", choices=["markdown", "md", "html"])
+    pub.add_argument("--description", default="Initial draft")
+    pub.add_argument("--workspace-id", default="")
+    pub.add_argument("--parent-id", default="")
+    pub.set_defaults(func=cmd_publish)
+    opn = sub.add_parser("open")
+    opn.add_argument("document_id")
+    opn.set_defaults(func=cmd_open)
+    st = sub.add_parser("status")
+    st.add_argument("document_id")
+    st.add_argument("--json", action="store_true")
+    st.set_defaults(func=cmd_status)
+    wss = sub.add_parser("workspaces")
+    wss.add_argument("--json", action="store_true")
+    wss.set_defaults(func=cmd_workspaces)
+    docs = sub.add_parser("documents")
+    docs.add_argument("--workspace-id", default="")
+    docs.add_argument("--json", action="store_true")
+    docs.set_defaults(func=cmd_documents)
+    search = sub.add_parser("search")
+    search.add_argument("query")
+    search.add_argument("--workspace-id", default="")
+    search.add_argument("--limit", type=int, default=10)
+    search.add_argument("--archived", action="store_true")
+    search.add_argument("--include-content", action="store_true")
+    search.add_argument("--json", action="store_true")
+    search.set_defaults(func=cmd_search)
+    doctor = sub.add_parser("doctor")
+    doctor.add_argument("--json", action="store_true")
+    doctor.set_defaults(func=cmd_doctor)
+    for name in ("health", "ready", "version"):
+        srv = sub.add_parser(name)
+        srv.set_defaults(func=cmd_server_info, kind=name)
+
+
+def _add_packet(sub: argparse._SubParsersAction) -> None:
+    pkt = sub.add_parser("packet")
+    pkt.add_argument("document_id")
+    pkt.add_argument("--format", choices=["json"], default="json")
+    pkt.add_argument("--thread-id", action="append")
+    pkt.add_argument("--v2", action="store_true",
+                     help="Use legacy packet v2 with sections")
+    pkt.set_defaults(func=cmd_packet)
+
+
+def _add_review_io(sub: argparse._SubParsersAction) -> None:
+    exp = sub.add_parser("export")
+    exp.add_argument("document_id")
+    exp.add_argument("--output", default="")
+    exp.set_defaults(func=cmd_export)
+    imp = sub.add_parser("import")
+    imp.add_argument("file")
+    imp.add_argument("--workspace-id", default="")
+    imp.add_argument("--parent-id", default="")
+    imp.set_defaults(func=cmd_import)
+
+
+def cmd_export(args: argparse.Namespace) -> None:
+    bundle = _client().export_review(args.document_id)
+    if args.output:
+        write_json(Path(args.output), bundle)
+        print(args.output)
+        return
+    print(json.dumps(bundle, indent=2, sort_keys=True))
+
+
+def cmd_import(args: argparse.Namespace) -> None:
+    bundle = read_json(Path(args.file))
+    scope = _workspace_scope(args.workspace_id or "", args.parent_id or "")
+    result = _client().import_review(
+        bundle, scope.workspace_id, scope.parent_id)
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="reviso")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    _add_basic(sub)
+    _add_packet(sub)
+    _add_review_io(sub)
+    add_guest_comment_commands(sub, _client)
+    add_invite_commands(sub, _client)
+    add_version_commands(sub, _client)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)

reviso_cli/cli/doctor.py

@@ -0,0 +1,88 @@
+"""CLI environment diagnostics."""
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+
+
+def doctor_report(client, server_url: str, token: str,
+                  workspace_id: str = "") -> dict:
+    checks = [
+        _static("server_config", bool(server_url), server_url or "not set"),
+        _static("auth_token", bool(token), _token_message(token)),
+        _call("health", client.health),
+        _call("ready", client.ready),
+        _call("version", client.version_info),
+        _call("workspaces", client.workspaces),
+        _mcp_check(server_url),
+    ]
+    if workspace_id:
+        checks.append(_workspace_check(checks[-2], workspace_id))
+    return {"ok": all(check["status"] != "fail" for check in checks),
+            "checks": checks}
+
+
+def print_doctor(report: dict) -> None:
+    for check in report["checks"]:
+        print(f"{check['status'].upper()}\t{check['name']}\t{check['message']}")
+    print("OK" if report["ok"] else "FAILED")
+
+
+def _static(name: str, ok: bool, message: str) -> dict:
+    return {"name": name, "status": "ok" if ok else "warn",
+            "message": message}
+
+
+def _call(name: str, func) -> dict:
+    try:
+        payload = func()
+    except SystemExit as exc:
+        return {"name": name, "status": "fail", "message": str(exc)}
+    except Exception as exc:  # noqa: BLE001 - diagnostic boundary.
+        return {"name": name, "status": "fail", "message": str(exc)}
+    return {"name": name, "status": "ok", "message": _summary(payload),
+            "payload": payload}
+
+
+def _mcp_check(server_url: str) -> dict:
+    if not server_url:
+        return {"name": "mcp_endpoint", "status": "warn",
+                "message": "server not set"}
+    req = urllib.request.Request(
+        f"{server_url.rstrip('/')}/mcp",
+        headers={"Accept": "application/json"},
+        method="GET",
+    )
+    try:
+        urllib.request.urlopen(req, timeout=5).read()
+    except urllib.error.HTTPError as exc:
+        if exc.code == 405:
+            return {"name": "mcp_endpoint", "status": "ok",
+                    "message": "reachable; POST JSON-RPC expected"}
+        return {"name": "mcp_endpoint", "status": "fail",
+                "message": f"HTTP {exc.code}"}
+    except Exception as exc:  # noqa: BLE001 - diagnostic boundary.
+        return {"name": "mcp_endpoint", "status": "fail",
+                "message": str(exc)}
+    return {"name": "mcp_endpoint", "status": "ok", "message": "reachable"}
+
+
+def _workspace_check(workspaces: dict, workspace_id: str) -> dict:
+    rows = (workspaces.get("payload") or {}).get("workspaces") or []
+    found = any(row.get("workspace_id") == workspace_id for row in rows)
+    return {"name": "workspace_scope", "status": "ok" if found else "fail",
+            "message": workspace_id if found else f"{workspace_id} not visible"}
+
+
+def _token_message(token: str) -> str:
+    return "set" if token else "missing REVISO_AUTOMATION_KEY"
+
+
+def _summary(payload: dict) -> str:
+    if "workspaces" in payload:
+        return f"{len(payload['workspaces'])} workspaces"
+    if "version" in payload:
+        return str(payload["version"])
+    if "status" in payload:
+        return str(payload["status"])
+    return "ok"

reviso_cli/cli/guest_comments.py

@@ -0,0 +1,61 @@
+"""CLI commands for guest comment workflows."""
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Callable
+
+
+def add_guest_comment_commands(sub: argparse._SubParsersAction,
+                               client_factory: Callable) -> None:
+    guest = sub.add_parser("guest")
+    guest.add_argument("document_id"); guest.add_argument("--name", required=True)
+    guest.add_argument("--email")
+    guest.set_defaults(func=lambda a: cmd_guest(a, client_factory))
+    comment = sub.add_parser("comment")
+    comment.add_argument("document_id")
+    comment.add_argument("--guest-id", default="")
+    comment.add_argument("--guest-token", default="")
+    comment.add_argument("--body", required=True)
+    comment.add_argument("--anchor-type", choices=["block", "selection"],
+                         default="block")
+    comment.add_argument("--block-id", default="")
+    comment.add_argument("--quote", default="")
+    comment.set_defaults(func=lambda a: cmd_comment(a, client_factory))
+    reply = sub.add_parser("reply")
+    reply.add_argument("thread_id")
+    reply.add_argument("--guest-id", default="")
+    reply.add_argument("--guest-token", default="")
+    reply.add_argument("--body", required=True)
+    reply.set_defaults(func=lambda a: cmd_reply(a, client_factory))
+    resolve = sub.add_parser("resolve")
+    resolve.add_argument("thread_id")
+    resolve.add_argument("--guest-id", default="")
+    resolve.add_argument("--guest-token", default="")
+    resolve.add_argument("--reason", required=True)
+    resolve.set_defaults(func=lambda a: cmd_resolve(a, client_factory))
+
+
+def cmd_guest(args: argparse.Namespace, client_factory: Callable) -> None:
+    result = client_factory().guest(args.document_id, args.name, args.email or None)
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+def cmd_comment(args: argparse.Namespace, client_factory: Callable) -> None:
+    anchor = {"type": args.anchor_type, "block_id": args.block_id,
+              "quote": args.quote}
+    result = client_factory().comment(args.document_id, args.guest_id,
+                                      args.guest_token, args.body, anchor)
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+def cmd_reply(args: argparse.Namespace, client_factory: Callable) -> None:
+    result = client_factory().reply(args.thread_id, args.guest_id,
+                                    args.guest_token, args.body)
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+def cmd_resolve(args: argparse.Namespace, client_factory: Callable) -> None:
+    result = client_factory().resolve(args.thread_id, args.guest_id,
+                                      args.guest_token, args.reason)
+    print(json.dumps(result, indent=2, sort_keys=True))

reviso_cli/cli/invites.py

@@ -0,0 +1,72 @@
+"""CLI invite commands.
+
+Anonymous share links are deliberately not part of this client. A share link
+carries a bearer token in its URL, and creating one is a browser action where the
+person handing it out can see who it is going to. Invites by email are here.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Callable
+
+from ..client import RevisoClient
+from ..access import invite_access_from_body, invite_for_public, invite_list_for_public
+
+
+def add_invite_commands(sub: argparse._SubParsersAction,
+                        client_factory: Callable[[], RevisoClient]) -> None:
+    invite = sub.add_parser("invite")
+    invite_sub = invite.add_subparsers(dest="invite_cmd", required=True)
+    create = invite_sub.add_parser("create")
+    create.add_argument("document_id")
+    create.add_argument("--email", required=True)
+    create.add_argument("--access", default="",
+                        choices=["view", "comment", "edit"])
+    create.add_argument("--json", action="store_true")
+    create.set_defaults(func=lambda a: _create(a, client_factory))
+    list_cmd = invite_sub.add_parser("list")
+    list_cmd.add_argument("document_id")
+    list_cmd.add_argument("--json", action="store_true")
+    list_cmd.set_defaults(func=lambda a: _list(a, client_factory))
+    revoke = invite_sub.add_parser("revoke")
+    revoke.add_argument("invite_id")
+    revoke.add_argument("--json", action="store_true")
+    revoke.set_defaults(func=lambda a: _revoke(a, client_factory))
+
+
+def _create(args: argparse.Namespace,
+            client_factory: Callable[[], RevisoClient]) -> None:
+    body = {}
+    if args.access:
+        body["access"] = args.access
+    access = invite_access_from_body(body)
+    result = invite_for_public(
+        client_factory().create_invite(
+            args.document_id, args.email, access))
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return
+    if result.get("existing"):
+        print(f"pending invite already exists: {result['invite_id']}")
+    else:
+        print(result.get("invite_url") or result["invite_id"])
+
+
+def _list(args: argparse.Namespace,
+          client_factory: Callable[[], RevisoClient]) -> None:
+    result = invite_list_for_public(client_factory().list_invites(args.document_id))
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return
+    for item in result.get("invites", []):
+        print(f"{item['id']}\t{item['status']}\t{item['access']}\t{item['email']}")
+
+
+def _revoke(args: argparse.Namespace,
+            client_factory: Callable[[], RevisoClient]) -> None:
+    result = client_factory().revoke_invite(args.invite_id)
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        print(f"{result['id']}: {result['status']}")

reviso_cli/cli/versions.py

@@ -0,0 +1,86 @@
+"""V1.0 version/edit CLI commands."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .. import command_journal
+
+
+def cmd_update(args: argparse.Namespace) -> None:
+    path = Path(args.file)
+    client = args.client_factory()
+    content = path.read_text()
+    fmt = format_file_arg(args, path)
+    # Journal key is USER inputs only -- NOT the dynamically resolved latest, so
+    # a rerun after a lost response does not drift onto the version the first run
+    # just committed. The concrete base resolved on first run is replayed via the
+    # stored request, keeping operation_id + base_version_id in lockstep (P1c).
+    parts = [args.document_id, content, args.description or "", fmt,
+             args.agent_name or "", args.base_version_id or ""]
+
+    def resolve() -> dict:
+        base = (args.base_version_id
+                or client.latest_content(args.document_id)["version_id"])
+        return {"base_version_id": base}
+
+    entry = command_journal.reserve("update", parts, resolve=resolve)
+    op = entry["operation_id"]
+    base = entry["request"]["base_version_id"]
+    result = client.update(args.document_id, content, base,
+                           args.description, fmt,
+                           args.agent_name, operation_id=op)
+    print(json.dumps(result, indent=2, sort_keys=True))
+    # Forget only after the local output step succeeded (see cmd_publish).
+    command_journal.forget("update", parts)
+
+
+def cmd_versions(args: argparse.Namespace) -> None:
+    print(json.dumps(args.client_factory().versions(args.document_id),
+                     indent=2, sort_keys=True))
+
+
+def cmd_diff(args: argparse.Namespace) -> None:
+    result = args.client_factory().diff(args.document_id, args.from_version_id,
+                                        args.to_version_id)
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        print("\n".join(result.get("unified_diff", [])))
+
+
+def cmd_rollback(args: argparse.Namespace) -> None:
+    client = args.client_factory()
+    base = args.base_version_id or client.latest_content(args.document_id)["version_id"]
+    result = client.rollback(args.document_id, args.target_version_id, base,
+                             args.description)
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+def add_version_commands(sub: argparse._SubParsersAction, client_factory) -> None:
+    upd = sub.add_parser("update")
+    upd.add_argument("document_id"); upd.add_argument("file")
+    upd.add_argument("--description", required=True)
+    upd.add_argument("--base-version-id", help="Version to base the update on (CAS). Omit to auto-base on the latest version (last-writer-wins); pass it for documents others are editing.")
+    upd.add_argument("--format", choices=["markdown", "md", "html"])
+    upd.add_argument("--agent-name", default="Agent")
+    upd.set_defaults(func=cmd_update, client_factory=client_factory)
+    vers = sub.add_parser("versions")
+    vers.add_argument("document_id")
+    vers.set_defaults(func=cmd_versions, client_factory=client_factory)
+    diff = sub.add_parser("diff")
+    diff.add_argument("document_id"); diff.add_argument("from_version_id")
+    diff.add_argument("to_version_id"); diff.add_argument("--json", action="store_true")
+    diff.set_defaults(func=cmd_diff, client_factory=client_factory)
+    rb = sub.add_parser("rollback")
+    rb.add_argument("document_id"); rb.add_argument("target_version_id")
+    rb.add_argument("--description", required=True)
+    rb.add_argument("--base-version-id")
+    rb.set_defaults(func=cmd_rollback, client_factory=client_factory)
+
+
+def format_file_arg(args: argparse.Namespace, path: Path) -> str:
+    if getattr(args, "format", None):
+        return "html" if args.format == "html" else "markdown"
+    return "html" if path.suffix.lower() in (".html", ".htm") else "markdown"