thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/commands/pull.py

@@ -0,0 +1,841 @@
+"""``tb pull`` command group.
+
+Refreshes local resource definitions from a ThingsBoard profile. The
+group has one subcommand per entity type (``dashboard``, ``device``,
+``asset``, ``rule-chain``, ``device-profile``, ``asset-profile``,
+``customer``, ``role``, ``entity-group``, ``user``) plus a bare-group
+callback that pulls every local entity in the resolved solution.
+
+The supporting modules do the heavy lifting — this file owns the CLI
+surface, request building, orchestration, dry-run rendering, output,
+and error handling:
+
+* :mod:`thingsboard_cli.core.assembler` discovers local entity files.
+* :mod:`thingsboard_cli.core.decomposer` turns the server response into a
+  validated write plan and applies it to disk.
+* :mod:`thingsboard_cli.core.git_dirty` checks whether the target files
+  are clean in git before any write happens.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Any
+
+import click
+import typer
+from filelock import Timeout as FileLockTimeout
+from rich.markup import escape
+from rich.table import Table
+from typer.core import TyperGroup
+
+from thingsboard_cli.commands.project import (
+    _humanize_entity_type,
+    _resolve_solution_dirs,
+    _rest_post,
+    _sorted_entity_types,
+    find_project_root,
+)
+from thingsboard_cli.common.options import ProfileOption
+from thingsboard_cli.config.resolver import resolve_profile
+from thingsboard_cli.core.assembler import discover_entity_files
+from thingsboard_cli.core.client import build_client
+from thingsboard_cli.core.decomposer import (
+    WriteAction,
+    WriteCounts,
+    WriteFailure,
+    WritePlan,
+    build_plan,
+    execute_plan,
+)
+from thingsboard_cli.core.exceptions import CLIError
+from thingsboard_cli.core.git_dirty import check_paths_dirty
+from thingsboard_cli.core.local import ENTITY_DIR_MAP
+from thingsboard_cli.core.output import busy_local_write_error, console, err_console, error, warning
+
+# All entity types ENTITY_DIR_MAP exposes — the kebab-case subcommand name is
+# the directory name with one trailing ``s`` dropped (verified:
+# "dashboards"->"dashboard", "entity-groups"->"entity-group",
+# "rule-chains"->"rule-chain", etc.). A bare ``rstrip("s")`` would strip
+# every trailing ``s``, which would silently break for a future entity dir
+# like ``addresses/`` (→ ``"addre"``).
+_SUBCOMMAND_NAMES: dict[str, str] = {
+    entity_type: (dir_name[:-1] if dir_name.endswith("s") else dir_name)
+    for entity_type, dir_name in ENTITY_DIR_MAP.items()
+}
+
+
+# Typer renders the long part of a docstring with a dim style by default; the
+# explicit ``[default not dim]…[/default not dim]`` markup wraps the prose so
+# the section heading and table read at the same intensity as the short
+# description. Requires ``rich_markup_mode="rich"`` on the Typer app below.
+_PULL_GROUP_HELP = """Refresh local resource definitions from ThingsBoard.
+
+[default not dim]Four calling shapes:
+
+  tb pull                     Refresh every locally-tracked entity in the
+                              resolved solution (one round trip).
+  tb pull -i                  Open an interactive picker to select entities
+                              across all types and pull them in one round
+                              trip. Useful for bootstrapping from a populated
+                              tenant.
+  tb pull <type> --all        Refresh every locally-tracked entity of one
+                              type (e.g. 'tb pull dashboard --all').
+  tb pull <type> <uuid>...    Fetch one or more entities by their
+                              server-internal UUID. Useful for picking up
+                              entities created on the server, or to refresh
+                              a specific entity by ID.
+
+Use --solution <name> to target a specific solution (auto-detected from cwd
+otherwise). --with-credentials opts device credentials into the pull (off
+by default). --dry-run prints the planned file writes without touching
+disk. --force skips the safety check that aborts when target files have
+uncommitted git changes.[/default not dim]
+"""
+
+
+class _PullGroup(TyperGroup):
+    """Custom group class so ``tb pull -i <uuid>`` errors clearly.
+
+    Without this override, ``-i`` followed by a positional argument makes
+    Click try to resolve that argument as a subcommand name (its default
+    behavior for groups), which produces a confusing
+    ``"No such command '<uuid>'"`` error. We intercept that case at
+    command-resolution time and raise our own usage error so the user
+    sees what they actually did wrong.
+
+    The argument after ``-i`` decides the message: a real subcommand name
+    (``tb pull -i dashboard``) gets the clear "remove the subcommand"
+    guidance, while anything else (a UUID) is reported as a positional
+    that ``-i`` doesn't take — instead of mislabelling a subcommand as a
+    UUID, or silently launching the picker and ignoring the subcommand.
+    """
+
+    def resolve_command(self, ctx: click.Context, args: list[str]) -> Any:
+        if ctx.params.get("interactive") and args:
+            if self.get_command(ctx, args[0]) is not None:
+                raise click.UsageError("-i applies to 'tb pull' only; remove the <type> subcommand.", ctx=ctx)
+            raise click.UsageError("-i does not accept positional UUIDs.", ctx=ctx)
+        return super().resolve_command(ctx, args)
+
+
+pull_app = typer.Typer(
+    name="pull",
+    help=_PULL_GROUP_HELP,
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    cls=_PullGroup,
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared context object — group-level flags propagate to subcommands here.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _PullOptions:
+    """Group-level options resolved once on the bare callback."""
+
+    solution: str | None
+    profile: str | None
+    force: bool
+    dry_run: bool
+    with_credentials: bool
+    interactive: bool = False
+
+
+def _stdout_isatty() -> bool:
+    """Return whether stdout is connected to a TTY (mockable for tests)."""
+    return bool(sys.stdout.isatty())
+
+
+def run_interactive_pull(
+    *,
+    opts: _PullOptions,
+    solution_dir: Path,
+    client: Any,
+    profile_label: str | None = None,
+) -> list[dict[str, str]] | None:
+    """Lazy-load the Textual picker and run it.
+
+    The picker implementation lives in :mod:`thingsboard_cli.core.interactive_pull`
+    and is imported on demand to keep ``tb pull`` (without ``-i``) free of
+    Textual import cost. Tests patch this module-level name directly, so the
+    real import never fires in unit tests.
+    """
+    # Tests patch this wrapper directly, so this import never fires under
+    # unit tests.
+    from thingsboard_cli.core.interactive_pull import run_interactive_pull as _impl
+
+    return _impl(opts=opts, solution_dir=solution_dir, client=client, profile_label=profile_label)
+
+
+# ---------------------------------------------------------------------------
+# Public entry points — the bare callback and one subcommand per entity type.
+# ---------------------------------------------------------------------------
+
+
+@pull_app.callback(invoke_without_command=True)
+def pull_callback(
+    ctx: typer.Context,
+    solution: Annotated[
+        str | None,
+        typer.Option("--solution", "-s", help="Target solution name (default: auto-detect or root)."),
+    ] = None,
+    profile: ProfileOption = None,
+    force: Annotated[bool, typer.Option("--force", help="Skip the git-dirty check before writing.")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Print the planned writes; do not modify files.")] = False,
+    with_credentials: Annotated[
+        bool,
+        typer.Option(
+            "--with-credentials",
+            help="Include device credentials in the pulled data (off by default).",
+        ),
+    ] = False,
+    interactive: Annotated[
+        bool,
+        typer.Option(
+            "--interactive",
+            "-i",
+            help="Open an interactive picker to select entities across all types.",
+        ),
+    ] = False,
+) -> None:
+    """Refresh local resource definitions from ThingsBoard.
+
+    Run 'tb pull' with no subcommand to refresh every locally-tracked
+    entity in the resolved solution. Run 'tb pull <type> --all' to refresh
+    every locally-tracked entity of one type. Run 'tb pull <type> <uuid>...'
+    to fetch one or more entities by their server-internal UUID.
+    """
+    ctx.obj = _PullOptions(
+        solution=solution,
+        profile=profile,
+        force=force,
+        dry_run=dry_run,
+        with_credentials=with_credentials,
+        interactive=interactive,
+    )
+    if ctx.invoked_subcommand is None:
+        _run_pull(ctx, entity_type_filter=None, uuids=[], all_flag=False)
+
+
+def _make_subcommand(entity_type: str, cmd_name: str) -> Callable[..., None]:
+    """Generate one ``tb pull <type>`` subcommand bound to *entity_type*.
+
+    Each subcommand accepts zero or more positional UUIDs and a mutually
+    exclusive ``--all`` flag. The group-level options (``--solution``,
+    ``--profile``, ``--force``, ``--dry-run``, ``--with-credentials``) are
+    also declared here so users can write either
+    ``tb pull --solution X device <uuid>`` or
+    ``tb pull device <uuid> --solution X``. Subcommand values merge over
+    parent-callback values (booleans OR together; the subcommand string
+    wins when set explicitly).
+
+    Implementation note: the inner function uses static, non-f-string
+    annotations because Python 3.14 evaluates annotations against the
+    function's ``__globals__`` (not its closure) when Typer inspects the
+    signature. We can't bake ``cmd_name`` into the help text via an
+    f-string in ``Annotated[...]`` for that reason — generic wording is
+    used and the per-subcommand help comes from the function's docstring.
+    """
+    uuid_help = f"One or more server-internal UUIDs of the {cmd_name}(s) to pull. Omit with --all."
+    all_help = f"Refresh every local {cmd_name} in the resolved solution."
+
+    def _subcommand(
+        ctx: typer.Context,
+        # Typer maps ``list[str]`` to a "zero-or-more" positional. When the user
+        # passes none, Typer hands us ``None``; we normalize to ``[]`` below.
+        # B008 is suppressed: the typer.Argument call is the standard Typer
+        # descriptor pattern (used identically throughout the codebase), not a
+        # mutable shared default.
+        uuids: list[str] = typer.Argument(None, help=uuid_help),  # noqa: B008
+        all_flag: bool = typer.Option(False, "--all", help=all_help),
+        solution: Annotated[
+            str | None,
+            typer.Option("--solution", "-s", help="Target solution name (default: auto-detect or root)."),
+        ] = None,
+        profile: ProfileOption = None,
+        force: Annotated[bool, typer.Option("--force", help="Skip the git-dirty check before writing.")] = False,
+        dry_run: Annotated[
+            bool, typer.Option("--dry-run", help="Print the planned writes; do not modify files.")
+        ] = False,
+        with_credentials: Annotated[
+            bool,
+            typer.Option(
+                "--with-credentials",
+                help="Include device credentials in the pulled data (off by default).",
+            ),
+        ] = False,
+        interactive: Annotated[
+            bool,
+            typer.Option(
+                "--interactive",
+                "-i",
+                help="Interactive picker — only valid on the bare 'tb pull' group.",
+            ),
+        ] = False,
+    ) -> None:
+        if interactive:
+            error("-i applies to 'tb pull' only; remove the <type> subcommand.")
+            return  # pragma: no cover
+        ctx.obj = _merge_options(
+            parent=_read_options(ctx),
+            solution=solution,
+            profile=profile,
+            force=force,
+            dry_run=dry_run,
+            with_credentials=with_credentials,
+        )
+        _run_pull(ctx, entity_type_filter=entity_type, uuids=list(uuids or []), all_flag=all_flag)
+
+    _subcommand.__name__ = f"pull_{cmd_name.replace('-', '_')}"
+    _subcommand.__doc__ = f"Refresh local {cmd_name} files from ThingsBoard."
+    return _subcommand
+
+
+# Bind one subcommand per entity type. The bare callback above stores the
+# group-level options in ``ctx.obj``; subcommands read them out by name so
+# the request-building / orchestration logic lives in one place
+# (:func:`_run_pull`).
+for _entity_type, _cmd_name in _SUBCOMMAND_NAMES.items():
+    pull_app.command(name=_cmd_name)(_make_subcommand(_entity_type, _cmd_name))
+
+
+# ---------------------------------------------------------------------------
+# Orchestration
+# ---------------------------------------------------------------------------
+
+
+def _run_pull(
+    ctx: typer.Context,
+    *,
+    entity_type_filter: str | None,
+    uuids: list[str],
+    all_flag: bool,
+) -> None:
+    """Drive a single ``tb pull`` invocation end-to-end.
+
+    *entity_type_filter* is None for the bare-group form (pull everything),
+    or an entity-type key for typed subcommands. *uuids* is the list of
+    positional arguments on a typed subcommand (one or more UUIDs); empty
+    means the user invoked ``--all`` or the bare-group form. *all_flag*
+    matches the ``--all`` switch on a typed subcommand.
+    """
+    opts = _read_options(ctx)
+
+    if opts.interactive:
+        if uuids:
+            error("-i does not accept positional UUIDs.")
+            return  # pragma: no cover
+        if all_flag:
+            error("-i and --all are mutually exclusive.")
+            return  # pragma: no cover
+        if not _stdout_isatty():
+            error("tb pull -i requires an interactive terminal.")
+            return  # pragma: no cover
+
+        project_root = find_project_root()
+        if project_root is None:
+            error("Not a ThingsBoard project. Run 'tb init' first.")
+            return  # pragma: no cover
+
+        resolved = resolve_profile(profile_name=opts.profile)
+        client = build_client(resolved)
+        solution_targets = [opts.solution] if opts.solution else None
+        dirs = _resolve_solution_dirs(project_root, solution_targets, push_all=False)
+        if not dirs:  # pragma: no cover — defensive
+            error("Could not resolve a solution directory.")
+            return
+        _, solution_dir = dirs[0]
+
+        # Resolve the profile name to display, so the picker shows the active
+        # profile by name instead of a generic "<active>" placeholder.
+        profile_label = opts.profile
+        if profile_label is None:
+            try:
+                from thingsboard_cli.config.manager import ConfigManager
+
+                profile_label = ConfigManager().get_default_profile_name()
+            except Exception:
+                profile_label = None
+        selection = run_interactive_pull(
+            opts=opts, solution_dir=solution_dir, client=client, profile_label=profile_label
+        )
+        if selection is None or not selection:
+            console.print("Cancelled, no changes.")
+            return
+        interactive_body: dict = {
+            "internalIds": selection,
+            "settings": _settings_dict(with_credentials=opts.with_credentials),
+        }
+        response = _call_export_api(client, interactive_body, profile_name=opts.profile)
+        try:
+            plans = build_plan(solution_dir, response)
+        except ValueError as exc:
+            error(str(exc))
+            return  # pragma: no cover
+        if opts.dry_run:
+            _render_dry_run_table(plans)
+            return
+        if not opts.force and not _confirm_overwrite_if_dirty(project_root, plans):
+            console.print("Cancelled, no changes.")
+            return
+        try:
+            counts = execute_plan(solution_dir, plans)
+        except WriteFailure as exc:
+            error(f"{exc} Re-run tb pull.")
+            return  # pragma: no cover
+        except FileLockTimeout:
+            busy_local_write_error()
+        _render_counts(counts, plans)
+        _render_dependency_warnings(response)
+        return
+
+    _reject_mutually_exclusive(uuids=uuids, all_flag=all_flag, entity_type_filter=entity_type_filter)
+
+    project_root = find_project_root()
+    if project_root is None:
+        error("Not a ThingsBoard project. Run 'tb init' first.")
+        return  # pragma: no cover
+
+    resolved = resolve_profile(profile_name=opts.profile)
+    client = build_client(resolved)
+
+    solution_targets = [opts.solution] if opts.solution else None
+    dirs = _resolve_solution_dirs(project_root, solution_targets, push_all=False)
+    # ``_resolve_solution_dirs`` returns exactly one entry for pull use
+    # (we don't expose --all over solutions); guard defensively.
+    if not dirs:  # pragma: no cover — defensive
+        error("Could not resolve a solution directory.")
+        return  # pragma: no cover
+    _, solution_dir = dirs[0]
+
+    # Soft warning when not in git: keep dry-run quiet and don't warn when
+    # ``--force`` is already in play.
+    if not opts.dry_run and not opts.force:
+        _maybe_warn_not_in_git(project_root)
+
+    body = _build_request_body(
+        solution_dir=solution_dir,
+        entity_type_filter=entity_type_filter,
+        uuids=uuids,
+        with_credentials=opts.with_credentials,
+    )
+    if body is None:
+        # Empty bulk request — short-circuited with a friendly hint already.
+        return
+
+    response = _call_export_api(client, body, profile_name=opts.profile)
+
+    try:
+        plans = build_plan(solution_dir, response)
+    except ValueError as exc:
+        error(str(exc))
+        return  # pragma: no cover
+
+    if opts.dry_run:
+        _render_dry_run_table(plans)
+        return
+
+    if not opts.force:
+        _enforce_git_clean(project_root, plans)
+
+    try:
+        counts = execute_plan(solution_dir, plans)
+    except WriteFailure as exc:
+        error(f"{exc} Re-run tb pull.")
+        return  # pragma: no cover
+    except FileLockTimeout:
+        busy_local_write_error()
+
+    _render_counts(counts, plans)
+    _render_dependency_warnings(response)
+
+
+# ---------------------------------------------------------------------------
+# Option / argument plumbing
+# ---------------------------------------------------------------------------
+
+
+def _read_options(ctx: typer.Context) -> _PullOptions:
+    """Return the group-level options stored on the parent context.
+
+    Falls back to defaults when the callback wasn't run (defensive — Typer
+    always runs the parent callback before a subcommand, but tests that
+    invoke subcommands programmatically might not).
+    """
+    if isinstance(ctx.obj, _PullOptions):
+        return ctx.obj
+    parent = ctx.parent
+    if parent is not None and isinstance(parent.obj, _PullOptions):
+        return parent.obj
+    return _PullOptions(
+        solution=None,
+        profile=None,
+        force=False,
+        dry_run=False,
+        with_credentials=False,
+        interactive=False,
+    )
+
+
+def _merge_options(
+    *,
+    parent: _PullOptions,
+    solution: str | None,
+    profile: str | None,
+    force: bool,
+    dry_run: bool,
+    with_credentials: bool,
+) -> _PullOptions:
+    """Combine subcommand-level options with the parent callback's values.
+
+    String options (solution, profile) take the subcommand value when
+    explicitly set (truthy), else fall back to the parent. Boolean flags
+    use a logical OR so the user can opt in at either layer — for example
+    ``tb pull --force device <uuid>`` and ``tb pull device <uuid> --force``
+    behave identically.
+    """
+    return _PullOptions(
+        solution=solution or parent.solution,
+        profile=profile or parent.profile,
+        force=force or parent.force,
+        dry_run=dry_run or parent.dry_run,
+        with_credentials=with_credentials or parent.with_credentials,
+        interactive=parent.interactive,
+    )
+
+
+def _reject_mutually_exclusive(*, uuids: list[str], all_flag: bool, entity_type_filter: str | None) -> None:
+    """Enforce subcommand-argument rules before any I/O happens."""
+    if entity_type_filter is None:
+        # Bare ``tb pull`` — no positional or --all to validate.
+        return
+    if uuids and all_flag:
+        error("Pass either a UUID or --all, not both.")
+    if not uuids and not all_flag:
+        error(f"Provide a UUID to refresh a single {_SUBCOMMAND_NAMES[entity_type_filter]} or pass --all.")
+
+
+# ---------------------------------------------------------------------------
+# Request body construction
+# ---------------------------------------------------------------------------
+
+# Static export settings dict — keys mirror the ``EntityExportSettings`` model's
+# ``serialization_alias`` field names so we can hand-roll the request body
+# without round-tripping through the Pydantic model (the wire layer expects
+# camelCase keys).
+_BASE_SETTINGS: dict[str, bool] = {
+    "exportRelations": True,
+    "exportAttributes": True,
+    "exportCredentials": False,
+    "exportCalculatedFields": True,
+    "exportPermissions": True,
+    "exportGroupEntities": True,
+    "embedGroupMembers": True,
+}
+
+
+def _settings_dict(*, with_credentials: bool) -> dict[str, bool]:
+    """Return the export settings payload, flipping credentials per CLI flag."""
+    settings = dict(_BASE_SETTINGS)
+    settings["exportCredentials"] = with_credentials
+    return settings
+
+
+def _build_request_body(
+    *,
+    solution_dir: Path,
+    entity_type_filter: str | None,
+    uuids: list[str],
+    with_credentials: bool,
+) -> dict | None:
+    """Construct the ``POST /api/solution/export`` body.
+
+    Returns ``None`` when bulk mode resolves to an empty list — the caller
+    has already printed the friendly hint, no server call should happen.
+    """
+    settings = _settings_dict(with_credentials=with_credentials)
+    if uuids and entity_type_filter is not None:
+        # Single mode — one or more internal UUIDs, server resolves each.
+        return {
+            "internalIds": [{"entityType": entity_type_filter, "id": uuid} for uuid in uuids],
+            "settings": settings,
+        }
+
+    # Bulk mode — collect external IDs from local files. Filter by type when
+    # the caller specified one (typed subcommand with --all).
+    external_ids: list[dict[str, str]] = []
+    for entity_type, _file_path, parsed in discover_entity_files(solution_dir):
+        if entity_type_filter is not None and entity_type != entity_type_filter:
+            continue
+        entity = parsed.get("entity") if isinstance(parsed, dict) else None
+        if not isinstance(entity, dict):
+            continue
+        ent_id = entity.get("id")
+        if not isinstance(ent_id, dict):
+            continue
+        raw = ent_id.get("id")
+        if not isinstance(raw, str) or not raw:
+            continue
+        external_ids.append({"entityType": entity_type, "id": raw})
+
+    if not external_ids:
+        if entity_type_filter is None:
+            console.print("No entities to pull. Add files locally or pull a specific entity by UUID.")
+        else:
+            hint_name = _SUBCOMMAND_NAMES[entity_type_filter]
+            console.print(f"No {hint_name}s in solution. Use 'tb pull {hint_name} <uuid>' to pull a specific one.")
+        return None
+
+    return {"externalIds": external_ids, "settings": settings}
+
+
+# ---------------------------------------------------------------------------
+# Wire layer
+# ---------------------------------------------------------------------------
+
+
+def _status_from_cli_error(exc: CLIError) -> int | None:
+    """Return the HTTP status code from a ``_rest_post`` CLIError, if any.
+
+    ``commands.project._rest_post`` raises :class:`HTTPCLIError` (a
+    :class:`CLIError` subclass) on non-2xx responses, with the status code
+    exposed as ``.status``. Returns ``None`` when the exception isn't an
+    HTTP one — keeping the caller's branching uniform across HTTP and
+    non-HTTP failure paths.
+    """
+    return getattr(exc, "status", None)
+
+
+_MISSING_IDS_HEADER_RE = re.compile(r"((?:External|Internal) ids not found):\s*(.+)", re.DOTALL)
+_TYPE_GROUP_RE = re.compile(r"([A-Z][A-Z_]*)\s*\[([^\]]+)\]")
+
+
+def _missing_ids_hint(server_msg: str) -> str:
+    """Pick the wrapper hint that fits the server's missing-ids variant.
+
+    External IDs are user-supplied at push time — a miss most likely
+    means the entity was never pushed. Internal IDs are server-assigned,
+    so the same hint would be misleading.
+    """
+    try:
+        if server_msg.lstrip().lower().startswith("external"):
+            return " — have they been pushed yet?"
+    except Exception:
+        pass
+    return ""
+
+
+def _format_missing_ids_message(server_msg: str) -> str:
+    """Reformat the server's missing-ids string into a multi-line layout.
+
+    The server returns one line, e.g.::
+
+        External ids not found: DEVICE [<uuid>], DEVICE_PROFILE [<uuid>, <uuid>]
+
+    Returns the same content laid out as one entity type per block and
+    one ID per line. The whole body is wrapped in a try/except — this
+    runs inside the error-rendering path, so a parser bug must never
+    eclipse the actual server error: on any unexpected input it falls
+    back to the raw server message.
+    """
+    try:
+        m = _MISSING_IDS_HEADER_RE.match(server_msg.strip())
+        if not m:
+            return server_msg
+        header, body = m.group(1), m.group(2)
+        groups = _TYPE_GROUP_RE.findall(body)
+        if not groups:
+            return server_msg
+        lines: list[str] = [f"{header}:"]
+        for entity_type, ids_str in groups:
+            ids = [i.strip() for i in ids_str.split(",") if i.strip()]
+            if not ids:
+                continue
+            lines.append(f"  {entity_type}:")
+            for id_ in ids:
+                lines.append(f"    {id_}")
+        return "\n".join(lines)
+    except Exception:
+        return server_msg
+
+
+def _call_export_api(
+    client: Any,
+    body: dict,
+    *,
+    profile_name: str | None,
+) -> dict:
+    """POST to ``/api/solution/export`` and handle the documented error shapes.
+
+    Returns the parsed JSON response on success. Aborts on 403 (permission)
+    and on 404 by surfacing the server's missing-ids message verbatim with
+    a hint that the most likely cause is the entities never having been
+    pushed. Other failures bubble up as the raw CLIError so the runtime's
+    default renderer handles them.
+    """
+    try:
+        return _rest_post(client, "/api/solution/export", body)
+    except CLIError as exc:
+        status = _status_from_cli_error(exc)
+        if status == 403:
+            label = profile_name or "<active>"
+            error(f"Profile '{label}' lacks VERSION_CONTROL READ permission.")
+        elif status == 404:
+            server_msg = getattr(exc, "server_message", "") or ""
+            if server_msg:
+                # Keep the server's "External/Internal ids not found" prefix
+                # intact — it tells the user which side of the mapping the
+                # miss was on. The hint suffix only fits the External case
+                # (internal IDs are server-assigned, so "push them" makes
+                # no sense for those).
+                formatted = _format_missing_ids_message(server_msg)
+                hint = _missing_ids_hint(server_msg)
+                error(f"Server can't find some IDs{hint}\n{formatted}")
+            # else fall through to the default error renderer.
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Git dirty + execution
+# ---------------------------------------------------------------------------
+
+
+def _maybe_warn_not_in_git(project_root: Path) -> None:
+    """Emit the once-per-pull soft warning when the project isn't in a git repo."""
+    result = check_paths_dirty(project_root, [])
+    if not result.in_git_repo:
+        warning(
+            "Project is not in a git repo — tb pull will overwrite files without diff safety. Use --dry-run to preview."
+        )
+
+
+def _plan_target_paths(plans: list[WritePlan]) -> list[Path]:
+    """Collect every path a write plan would touch (new + the renamed-from path)."""
+    paths: list[Path] = []
+    for plan in plans:
+        paths.append(plan.new_path)
+        if plan.action == WriteAction.RENAME and plan.existing_local_path is not None:
+            paths.append(plan.existing_local_path)
+    return paths
+
+
+def _confirm_overwrite_if_dirty(project_root: Path, plans: list[WritePlan]) -> bool:
+    """Interactive-pull variant of the git-dirty guard.
+
+    Returns ``True`` when it is safe to write (not in a git repo, nothing
+    dirty, or the user confirmed the overwrite) and ``False`` when the user
+    declined. Unlike :func:`_enforce_git_clean`, a dirty tree *prompts*
+    instead of aborting the process — the picker selection is expensive to
+    rebuild, so we never throw it away over a recoverable file conflict.
+    """
+    try:
+        result = check_paths_dirty(project_root, _plan_target_paths(plans))
+    except RuntimeError as exc:
+        error(str(exc))
+        return False  # pragma: no cover — error() is NoReturn
+    if not result.in_git_repo or not result.dirty_paths:
+        return True
+    err_console.print("[red]Local changes would be overwritten:[/red]")
+    for p in result.dirty_paths:
+        err_console.file.write(f"  {p}\n")
+    err_console.file.flush()
+    return typer.confirm("Overwrite these files?", default=False)
+
+
+def _enforce_git_clean(project_root: Path, plans: list[WritePlan]) -> None:
+    """Abort if any planned target file is dirty in git.
+
+    Outside a git repo we already emitted the soft warning earlier; the
+    check_paths_dirty call here returns ``in_git_repo=False`` and we simply
+    return. ``--force`` short-circuits this function entirely (handled by
+    the caller).
+    """
+    try:
+        result = check_paths_dirty(project_root, _plan_target_paths(plans))
+    except RuntimeError as exc:
+        error(str(exc))
+        return  # pragma: no cover
+    if not result.in_git_repo:
+        return
+    if result.dirty_paths:
+        # Rich crops long paths inside a Panel (and even at console width)
+        # when the path exceeds the available cells, which would hide the
+        # very paths the user needs to act on. Write paths to the raw stderr
+        # stream so the file names always reach the user regardless of
+        # terminal width.
+        err_console.print("[red]Local changes would be overwritten:[/red]")
+        for p in result.dirty_paths:
+            err_console.file.write(f"  {p}\n")
+        err_console.file.flush()
+        error("Commit/stash them or pass --force.")
+
+
+# ---------------------------------------------------------------------------
+# Output
+# ---------------------------------------------------------------------------
+
+
+def _render_dry_run_table(plans: list[WritePlan]) -> None:
+    """Print the dry-run plan as a Rich table."""
+    if not plans:
+        console.print("No changes — local files already match the server.")
+        return
+
+    table = Table(title="Planned writes (dry-run)")
+    table.add_column("Action")
+    table.add_column("Type")
+    table.add_column("External ID")
+    table.add_column("Path")
+
+    for plan in plans:
+        path_display = str(plan.new_path)
+        if plan.action == WriteAction.RENAME and plan.existing_local_path is not None:
+            path_display = f"{plan.existing_local_path} → {plan.new_path}"
+        table.add_row(plan.action.value, plan.entity_type, plan.external_id, path_display)
+
+    console.print(table)
+
+
+def _render_counts(counts: dict[str, WriteCounts], plans: list[WritePlan]) -> None:
+    """Print the per-entity-type rollup plus per-rename follow-up lines."""
+    if not any((c.created or c.updated or c.renamed) for c in counts.values()):
+        console.print("No changes — local files already match the server.")
+        return
+
+    renames_by_type: dict[str, list[WritePlan]] = {}
+    for plan in plans:
+        if plan.action == WriteAction.RENAME:
+            renames_by_type.setdefault(plan.entity_type, []).append(plan)
+
+    for entity_type in _sorted_entity_types(counts.keys()):
+        count = counts[entity_type]
+        if not (count.created or count.updated or count.renamed):
+            continue
+        parts: list[str] = []
+        if count.updated:
+            parts.append(f"{count.updated} updated")
+        if count.created:
+            parts.append(f"{count.created} created")
+        if count.renamed:
+            parts.append(f"{count.renamed} renamed")
+        console.print(f"{_humanize_entity_type(entity_type)}: {', '.join(parts)}")
+        for plan in renames_by_type.get(entity_type, []):
+            old_name = plan.existing_local_path.name if plan.existing_local_path is not None else "?"
+            console.print(f"  {old_name} → {plan.new_path.name}")
+
+
+def _render_dependency_warnings(response_body: dict) -> None:
+    """Render any ``warnings`` returned by the server."""
+    warnings_list = response_body.get("warnings") if isinstance(response_body, dict) else None
+    if not isinstance(warnings_list, list):
+        return
+    for w in warnings_list:
+        warning(f"Dependency warning: {escape(str(w))}")