thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/commands/project.py

@@ -0,0 +1,1018 @@
+"""Project management commands: init, push, and validate for IaC-style resource sync."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import time
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Annotated, Any
+
+import click
+import typer
+from rich.markup import escape
+
+from thingsboard_cli.commands._pagination import coerce_page_kwargs
+from thingsboard_cli.common.options import ProfileOption
+from thingsboard_cli.config.resolver import resolve_profile
+from thingsboard_cli.core.client import build_client
+from thingsboard_cli.core.output import console, error, pluralize, success, warning
+
+DEFAULT_GITIGNORE = """\
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# OS
+.DS_Store
+
+# Local-only files
+solution.json
+*.local.*
+
+# Editor / tooling
+.claude/
+"""
+
+
+def _rest_post(client: Any, path: str, data: dict) -> dict:
+    """Direct REST POST, bypassing tb-pe-client Pydantic validation.
+
+    Workaround for tb-pe-client bug where ``serialization_alias`` fields
+    (e.g. ``entityType``) are rejected during input validation because
+    Pydantic only accepts the Python field name for validation.
+
+    Because this path bypasses ``DebugClient`` (the proxy only intercepts
+    callable attributes on the SDK client, not direct ``api_client.rest_client``
+    access), ``--debug``/``TB_DEBUG=1`` would otherwise show nothing for
+    push/validate. We emit the request and response here ourselves so debug
+    mode is useful end-to-end.
+    """
+    from thingsboard_cli.core.debug import is_debug, print_debug
+    from thingsboard_cli.core.exceptions import HTTPCLIError
+
+    ac = client.api_client
+    url = ac.configuration.host + path
+    headers = dict(ac.default_headers)
+    headers["Content-Type"] = "application/json"
+    headers["Accept"] = "application/json"
+    ac.update_params_for_auth(
+        headers,
+        [],
+        ["ApiKeyForm", "HttpLoginForm"],
+        resource_path=path,
+        method="POST",
+        body=data,
+    )
+
+    if is_debug():
+        print_debug(f"POST {path} → request", {"url": url, "headers": headers, "body": data})
+
+    response = ac.rest_client.request("POST", url, headers=headers, body=data)
+    raw_body = response.read()
+    body_text = raw_body.decode("utf-8", errors="replace") if isinstance(raw_body, bytes) else raw_body
+
+    if is_debug():
+        print_debug(
+            f"POST {path} → response",
+            {"status": response.status, "reason": response.reason, "body": body_text},
+        )
+
+    if not 200 <= response.status <= 299:
+        # Always lead with the HTTP status so users see at least *something*
+        # actionable even when the server's message is empty or opaque (e.g.
+        # Jackson "Type definition error: [simple type, class …]" leaks).
+        prefix = f"HTTP {response.status} {response.reason or ''}".strip()
+
+        server_message = ""
+        error_code: Any = None
+        if body_text:
+            try:
+                err_data = json.loads(body_text)
+                if isinstance(err_data, dict):
+                    server_message = (
+                        err_data.get("message") or err_data.get("errorMessage") or err_data.get("error") or ""
+                    )
+                    error_code = err_data.get("errorCode")
+                else:
+                    server_message = body_text
+            except (ValueError, TypeError):
+                server_message = body_text
+
+        parts = [prefix]
+        if server_message:
+            parts.append(server_message.strip())
+        if error_code is not None and error_code != "":
+            parts.append(f"(errorCode={error_code})")
+        # When the structured message is short/opaque (≤120 chars and no
+        # newline), append the raw body so debugging the request doesn't
+        # require re-running with --debug. Capped to keep the panel readable.
+        if body_text and (not server_message or (len(server_message) <= 120 and "\n" not in server_message)):
+            raw = body_text.strip()
+            if raw and raw != server_message:
+                if len(raw) > 800:
+                    raw = raw[:800] + "…"
+                parts.append(f"\nResponse body: {raw}")
+
+        raise HTTPCLIError("\n".join(parts), status=response.status, server_message=server_message.strip())
+
+    return json.loads(body_text) if body_text else {}
+
+
+MARKER_FILE = "thingsboard.json"
+
+
+def _find_scaffold_dir() -> Path:
+    """Locate the bundled scaffold directory.
+
+    Checks two locations:
+    - Inside the installed package (force-included during wheel build)
+    - At the project root (development / editable install)
+    """
+    # Installed package: scaffold/ is force-included into the wheel
+    pkg_path = Path(__file__).resolve().parent.parent / "scaffold"
+    if pkg_path.is_dir():
+        return pkg_path
+    # Development: scaffold/ lives at the repo root
+    dev_path = Path(__file__).resolve().parent.parent.parent.parent / "scaffold"
+    if dev_path.is_dir():
+        return dev_path
+    msg = "scaffold directory not found — package may be installed incorrectly"
+    raise FileNotFoundError(msg)
+
+
+SCAFFOLD_DIR = _find_scaffold_dir()
+
+
+def _find_bundled_resources_dir() -> Path | None:
+    """Locate the bundled resources directory.
+
+    Resources live inside the package at thingsboard_cli/resources/ — they are
+    picked up automatically by hatch since they sit under src/. Returns None
+    if the directory is missing (e.g. in a partially built editable install
+    before the manual sync script has been run).
+    """
+    pkg_path = Path(__file__).resolve().parent.parent / "resources"
+    if pkg_path.is_dir():
+        return pkg_path
+    return None
+
+
+BUNDLED_RESOURCES_DIR = _find_bundled_resources_dir()
+
+
+def find_project_root() -> Path | None:
+    """Walk up from cwd looking for thingsboard.json.
+
+    Returns the directory containing the marker file, or None if not found.
+    """
+    current = Path.cwd().resolve()
+    while True:
+        if (current / MARKER_FILE).is_file():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def _copy_scaffold(project_root: Path) -> list[str]:
+    """Copy all scaffold contents to the project, with conflict handling.
+
+    Returns a list of status labels for display.
+
+    The bundled scaffold ``.gitignore`` is intentionally skipped — the
+    ``init_command`` writes a richer default in its place (see
+    ``DEFAULT_GITIGNORE``).
+    """
+    from thingsboard_cli.core.scaffold import _copy_with_substitutions
+
+    statuses: list[str] = []
+    ignore = shutil.ignore_patterns(".gitkeep")
+
+    def _copy_file(src: str, dst: str) -> str:
+        src_path = Path(src)
+        dst_path = Path(dst)
+        rel = src_path.relative_to(SCAFFOLD_DIR).as_posix()
+        _copy_with_substitutions(src_path, dst_path, rel)
+        return dst
+
+    def _copy_top_level(src: Path, dst: Path) -> None:
+        rel = src.relative_to(SCAFFOLD_DIR).as_posix()
+        _copy_with_substitutions(src, dst, rel)
+
+    for item in sorted(SCAFFOLD_DIR.iterdir()):
+        if item.name in {"manifest.json", ".gitignore"}:
+            continue
+        dst = project_root / item.name
+        if item.is_dir():
+            if not dst.exists():
+                shutil.copytree(item, dst, ignore=ignore, copy_function=_copy_file)
+                statuses.append(f"{item.name}/")
+            else:
+                action = typer.prompt(
+                    f"{item.name}/ already exists — overwrite or skip?",
+                    type=click.Choice(["overwrite", "skip"]),
+                    default="skip",
+                )
+                if action == "overwrite":
+                    shutil.rmtree(dst)
+                    shutil.copytree(item, dst, ignore=ignore, copy_function=_copy_file)
+                    statuses.append(f"{item.name}/ (overwritten)")
+                else:
+                    statuses.append(f"{item.name}/ (skipped)")
+        else:
+            if item.name == ".gitkeep":
+                continue
+            if not dst.exists():
+                _copy_top_level(item, dst)
+                statuses.append(item.name)
+            else:
+                action = typer.prompt(
+                    f"{item.name} already exists — overwrite or skip?",
+                    type=click.Choice(["overwrite", "skip"]),
+                    default="skip",
+                )
+                if action == "overwrite":
+                    _copy_top_level(item, dst)
+                    statuses.append(f"{item.name} (overwritten)")
+                else:
+                    statuses.append(f"{item.name} (skipped)")
+
+    return statuses
+
+
+def _format_init_path(project_root: Path) -> str:
+    """Render a project root path for the init success line.
+
+    Prefer a path relative to cwd when one exists (avoids long absolute paths
+    that wrap awkwardly in narrow terminals); otherwise fall back to the
+    absolute path.
+    """
+    try:
+        cwd = Path.cwd().resolve()
+        rel = project_root.resolve().relative_to(cwd)
+        rel_str = str(rel)
+        return rel_str if rel_str not in ("", ".") else "."
+    except ValueError:
+        return str(project_root)
+
+
+def _write_default_gitignore(project_root: Path) -> str:
+    """Write the default ``.gitignore`` if one does not already exist.
+
+    Returns a status label for the success display; the empty string when an
+    existing file was left untouched.
+    """
+    gitignore_path = project_root / ".gitignore"
+    if gitignore_path.exists():
+        return ".gitignore (skipped)"
+    gitignore_path.write_text(DEFAULT_GITIGNORE)
+    return ".gitignore"
+
+
+def init_command() -> None:
+    """Initialize a ThingsBoard project directory."""
+    # Lazy import to avoid circular dependency (local.py imports find_project_root)
+    from thingsboard_cli.core.local import ENTITY_DIR_MAP
+
+    entity_dirs = sorted(ENTITY_DIR_MAP.values())
+
+    project_root = Path.cwd()
+    marker_path = project_root / MARKER_FILE
+
+    if marker_path.is_file():
+        console.print(f"Already initialized (found {MARKER_FILE})")
+        return
+
+    for dirname in entity_dirs:
+        (project_root / dirname).mkdir(exist_ok=True)
+
+    (project_root / "tasks").mkdir(exist_ok=True)
+
+    scaffold_statuses = _copy_scaffold(project_root)
+    gitignore_status = _write_default_gitignore(project_root)
+
+    from thingsboard_cli.core.scaffold import (
+        compute_local_scaffold_hash,
+        get_scaffold_manifest,
+    )
+
+    manifest = get_scaffold_manifest(SCAFFOLD_DIR)
+    scaffold_version = manifest.get("version", 1) if manifest else 1
+    scaffold_hash = compute_local_scaffold_hash(project_root, SCAFFOLD_DIR)
+
+    marker_data = {
+        "version": 2,
+        "mode": "local",
+        "scaffold_version": scaffold_version,
+        "scaffold_content_hash": scaffold_hash,
+    }
+    marker_path.write_text(json.dumps(marker_data, indent=2) + "\n")
+
+    # Initialize git repo if not already inside one. Failures here only warn
+    # — the project dirs/marker are already on disk, so a half-initialized
+    # state shouldn't bubble up as a hard error.
+    git_initialized = False
+    git_init_warning: str | None = None
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            cwd=project_root,
+        )
+        if result.returncode != 0:
+            subprocess.run(["git", "init"], cwd=project_root, capture_output=True, check=True)
+            git_initialized = True
+    except FileNotFoundError:
+        pass  # git not installed — skip silently
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr.decode().strip() if isinstance(exc.stderr, bytes) else (exc.stderr or "").strip()) or str(
+            exc
+        )
+        git_init_warning = f"git init failed: {stderr}"
+
+    success(f"Initialized ThingsBoard project in {_format_init_path(project_root)}")
+    if git_initialized:
+        console.print("  git repository initialized")
+    if git_init_warning:
+        warning(git_init_warning)
+    for dirname in entity_dirs:
+        console.print(f"  {dirname}/")
+    console.print("  tasks/")
+    if gitignore_status:
+        console.print(f"  {gitignore_status}")
+    for status in scaffold_statuses:
+        console.print(f"  {status}")
+
+
+def _format_server_message(item: Any) -> str:
+    """Format a server-side validation entry for display.
+
+    The API may return strings or structured objects (e.g. with
+    ``entityType``, ``entityName``/``name``, ``path``, ``errorMessage``,
+    ``message`` fields). When given a dict, render the most useful fields
+    inline so the user sees the offending file/entity and the underlying
+    server message.
+    """
+    if isinstance(item, str):
+        return item
+    if not isinstance(item, dict):
+        return str(item)
+
+    entity_type = item.get("entityType") or item.get("type")
+    name = item.get("entityName") or item.get("name")
+    path = item.get("path") or item.get("file")
+    msg = item.get("errorMessage") or item.get("message") or item.get("error")
+
+    label_parts: list[str] = []
+    if entity_type and name:
+        label_parts.append(f"{entity_type} '{name}'")
+    elif entity_type:
+        label_parts.append(str(entity_type))
+    elif name:
+        label_parts.append(f"'{name}'")
+    if path:
+        label_parts.append(f"({path})")
+
+    label = " ".join(label_parts)
+    if label and msg:
+        return f"{label}: {msg}"
+    if label:
+        return label
+    if msg:
+        return str(msg)
+    # Fallback: render the raw dict so users still see *something*.
+    return ", ".join(f"{k}={v}" for k, v in item.items())
+
+
+def _local_entity_count(solution_data: dict) -> int:
+    """Total number of entities discovered locally for *solution_data*."""
+    entities = solution_data.get("entities") or {}
+    return sum(len(v) for v in entities.values())
+
+
+# Sentence-case plural labels for every TB EntityType. Explicit mappings keep
+# acronyms uppercase (AI, API, RPC, OTA, TB, OAuth2) and handle irregular
+# English plurals (BLOB_ENTITY -> "Blob entities") that the +s fallback can't.
+# Anything not listed falls through to the algorithmic +s formatter.
+_ENTITY_TYPE_LABELS: dict[str, str] = {
+    "TENANT": "Tenants",
+    "CUSTOMER": "Customers",
+    "USER": "Users",
+    "DASHBOARD": "Dashboards",
+    "ASSET": "Assets",
+    "DEVICE": "Devices",
+    "ALARM": "Alarms",
+    "ENTITY_GROUP": "Entity groups",
+    "CONVERTER": "Converters",
+    "INTEGRATION": "Integrations",
+    "RULE_CHAIN": "Rule chains",
+    "RULE_NODE": "Rule nodes",
+    "SCHEDULER_EVENT": "Scheduler events",
+    "BLOB_ENTITY": "Blob entities",
+    "REPORT_TEMPLATE": "Report templates",
+    "REPORT": "Reports",
+    "ENTITY_VIEW": "Entity views",
+    "WIDGETS_BUNDLE": "Widgets bundles",
+    "WIDGET_TYPE": "Widget types",
+    "ROLE": "Roles",
+    "GROUP_PERMISSION": "Group permissions",
+    "TENANT_PROFILE": "Tenant profiles",
+    "DEVICE_PROFILE": "Device profiles",
+    "ASSET_PROFILE": "Asset profiles",
+    "API_USAGE_STATE": "API usage states",
+    "TB_RESOURCE": "TB resources",
+    "OTA_PACKAGE": "OTA packages",
+    "EDGE": "Edges",
+    "RPC": "RPCs",
+    "QUEUE": "Queues",
+    "NOTIFICATION_TARGET": "Notification targets",
+    "NOTIFICATION_TEMPLATE": "Notification templates",
+    "NOTIFICATION_REQUEST": "Notification requests",
+    "NOTIFICATION": "Notifications",
+    "NOTIFICATION_RULE": "Notification rules",
+    "QUEUE_STATS": "Queue stats",
+    "OAUTH2_CLIENT": "OAuth2 clients",
+    "DOMAIN": "Domains",
+    "MOBILE_APP": "Mobile apps",
+    "MOBILE_APP_BUNDLE": "Mobile app bundles",
+    "CALCULATED_FIELD": "Calculated fields",
+    "JOB": "Jobs",
+    "SECRET": "Secrets",
+    "ADMIN_SETTINGS": "Admin settings",
+    "AI_MODEL": "AI models",
+    "API_KEY": "API keys",
+}
+
+
+# Order in which entity types are displayed in push/validate output. Groups
+# what the user cares about: data assets (paired with their profiles), then
+# visualisation (dashboards), then processing (rule chains), then access
+# governance. Types not listed here render after these in alphabetical order
+# so a server-side addition still shows up predictably.
+_DISPLAY_ORDER: list[str] = [
+    "DEVICE",
+    "DEVICE_PROFILE",
+    "ASSET",
+    "ASSET_PROFILE",
+    "DASHBOARD",
+    "RULE_CHAIN",
+    "USER",
+    "CUSTOMER",
+    "ROLE",
+    "ENTITY_GROUP",
+]
+
+
+def _sorted_entity_types(entity_types: Iterable[str]) -> list[str]:
+    """Order entity types by ``_DISPLAY_ORDER``; unknowns trail alphabetically.
+
+    Duplicate entries are collapsed (the first occurrence wins) so callers can
+    pass a chained iterable without worrying about repeats.
+    """
+    seen: set[str] = set()
+    unique: list[str] = []
+    for entity_type in entity_types:
+        if entity_type not in seen:
+            seen.add(entity_type)
+            unique.append(entity_type)
+
+    order_index = {t: i for i, t in enumerate(_DISPLAY_ORDER)}
+    sentinel = len(_DISPLAY_ORDER)
+    return sorted(unique, key=lambda t: (order_index.get(t, sentinel), t))
+
+
+def _humanize_entity_type(entity_type: str) -> str:
+    """Render a TB entity-type enum as a sentence-case plural label.
+
+    Looks up ``_ENTITY_TYPE_LABELS`` first (handles acronyms and irregular
+    plurals); falls back to a generic ``FOO_BAR`` -> ``Foo bars`` formatter
+    for future enum entries the map doesn't list yet.
+    """
+    if not entity_type:
+        return entity_type
+    label = _ENTITY_TYPE_LABELS.get(entity_type)
+    if label is not None:
+        return label
+    words = entity_type.lower().replace("_", " ")
+    return f"{words[:1].upper()}{words[1:]}s"
+
+
+def _validate_and_display(client: Any, solution_data: dict, *, brief_when_valid: bool = False) -> bool:
+    """Validate a solution against ThingsBoard and display results.
+
+    When ``brief_when_valid`` is True and validation passes, the per-entity-type
+    summary is omitted — used by ``tb push`` to avoid duplicating the breakdown
+    that the post-import counts will print anyway. On failure, the full summary
+    is always shown so the user can see what was checked.
+
+    Returns True if validation passed, False otherwise.
+    """
+    result = _rest_post(client, "/api/solution/validate", solution_data)
+
+    is_valid = result.get("valid", False)
+    summary = result.get("entitySummary") or {}
+    conflicts = result.get("conflicts") or []
+    warnings = result.get("warnings") or []
+
+    # Use the local entity count for the headline so the displayed total
+    # matches what the user has on disk even if the server omits an
+    # ``entitySummary`` (e.g. when validation aborts early). When called
+    # from ``tb push`` (``brief_when_valid=True``) and validation passed,
+    # the count is omitted because the subsequent "Pushed solution (N…)"
+    # line repeats it verbatim.
+    total = _local_entity_count(solution_data)
+    status = "passed" if is_valid else "failed"
+    style = "green" if is_valid else "red"
+    if brief_when_valid and is_valid:
+        console.print(f"Validation [{style}]{status}[/{style}]")
+    else:
+        console.print(f"Validation [{style}]{status}[/{style}] ({pluralize(total, 'entity', 'entities')})")
+
+    if not (brief_when_valid and is_valid):
+        for entity_type in _sorted_entity_types(str(k) for k in summary):
+            count = summary[entity_type]
+            label = _humanize_entity_type(entity_type)
+            console.print(f"  {escape(label):20s} {count}")
+
+    if conflicts:
+        console.print("\n[red]Conflicts:[/red]")
+        for c in conflicts:
+            console.print(f"  - {escape(_format_server_message(c))}")
+
+    if warnings:
+        console.print("\n[yellow]Warnings:[/yellow]")
+        for w in warnings:
+            console.print(f"  - {escape(_format_server_message(w))}")
+
+    return bool(is_valid)
+
+
+def _detect_solution_from_cwd(project_root: Path) -> str | None:
+    """If cwd is inside ``project_root/solutions/<name>/``, return that name."""
+    try:
+        cwd = Path.cwd().resolve()
+        solutions_dir = (project_root / "solutions").resolve()
+        rel = cwd.relative_to(solutions_dir)
+        return rel.parts[0] if rel.parts else None
+    except (ValueError, IndexError):
+        return None
+
+
+def _list_available_solutions(project_root: Path) -> list[str]:
+    """Return sorted names of every directory under ``solutions/``."""
+    solutions_dir = project_root / "solutions"
+    if not solutions_dir.is_dir():
+        return []
+    return sorted(p.name for p in solutions_dir.iterdir() if p.is_dir())
+
+
+def _resolve_solution_dirs(
+    project_root: Path,
+    targets: list[str] | None,
+    push_all: bool = False,
+) -> list[tuple[str, Path]]:
+    """Resolve which solution directories to operate on.
+
+    When *targets* names a value that is not an existing solution directory,
+    raise a clear error listing the available solutions instead of silently
+    falling back to the root entities (P0-09). File or directory path
+    arguments are not honored — see ``push_command`` help text.
+    """
+    solutions_dir = project_root / "solutions"
+    is_multi = solutions_dir.is_dir() and any(solutions_dir.iterdir())
+
+    dirs: list[tuple[str, Path]] = []
+
+    if push_all and is_multi:
+        dirs.append(("root", project_root))
+        for sol in sorted(solutions_dir.iterdir()):
+            if sol.is_dir():
+                dirs.append((sol.name, sol))
+    elif targets:
+        # ``tb push solA solB`` historically dropped extras silently. Reject
+        # multi-solution invocations explicitly so the dropped argument
+        # surfaces — multi-target across profiles is the supported workflow.
+        if len(targets) > 1:
+            error(
+                f"Pass a single solution name; got {len(targets)}: {', '.join(targets)}. "
+                "Use --all to operate on every solution, or run the command "
+                "once per solution / profile."
+            )
+        name = targets[0]
+        sol_path = solutions_dir / name
+        if sol_path.is_dir():
+            dirs.append((name, sol_path))
+        else:
+            available = _list_available_solutions(project_root)
+            if available:
+                listing = ", ".join(available)
+                msg = f"Unknown solution '{name}'. Available solutions: {listing}"
+            else:
+                msg = (
+                    f"Unknown solution '{name}'. No solutions defined under "
+                    f"{solutions_dir} — create one with 'tb solution new <name>' "
+                    "or omit the argument to operate on root entities."
+                )
+            error(msg)
+    else:
+        # Auto-detect solution from cwd
+        detected = _detect_solution_from_cwd(project_root) if is_multi else None
+        if detected:
+            dirs.append((detected, solutions_dir / detected))
+        else:
+            dirs.append(("root", project_root))
+
+    return dirs
+
+
+def _get_timeseries_keys(client: Any, entity_type: str, entity_id: str) -> list[str]:
+    """List existing timeseries keys for an entity. Raises on transport errors."""
+    from thingsboard_cli.core.client import authed_request
+
+    path = f"/api/plugins/telemetry/{entity_type}/{entity_id}/keys/timeseries"
+    response = authed_request(client, "GET", path)
+    body = response.read()
+    if isinstance(body, bytes):
+        body = body.decode("utf-8")
+    if not body:
+        return []
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError:
+        return []
+    return [str(k) for k in data] if isinstance(data, list) else []
+
+
+def _delete_telemetry_keys(client: Any, entity_type: str, entity_id: str, keys: list[str]) -> None:
+    """Delete the given timeseries keys for an entity (all data)."""
+    from urllib.parse import quote, urlencode
+
+    from thingsboard_cli.core.client import authed_request
+
+    if not keys:
+        return
+    query = urlencode(
+        {
+            "keys": ",".join(keys),
+            "deleteAllDataForKeys": "true",
+        },
+        quote_via=quote,
+    )
+    path = f"/api/plugins/telemetry/{entity_type}/{entity_id}/timeseries/delete?{query}"
+    authed_request(client, "DELETE", path)
+
+
+def _run_emulators(
+    client: Any,
+    solution_dir: Path,
+    import_result: dict,
+    *,
+    force: bool = False,
+) -> None:
+    """Execute telemetry emulators after solution import.
+
+    For each emulator task:
+      1. Resolve external entity ID via the import response's ``idMapping``.
+      2. Check existing telemetry keys on the device.
+      3. Skip if any emulated key already has data (unless ``force`` is set).
+      4. With ``force``: DELETE the overlapping keys, then POST fresh data.
+      5. Otherwise: POST the generated telemetry directly.
+    """
+    # Lazy imports keep the module import-light at startup.
+    from thingsboard_cli.core.client import authed_request
+    from thingsboard_cli.core.emulator.models import EmulatorTask
+    from thingsboard_cli.core.emulator.runtime import DeviceEmulator
+    from thingsboard_cli.core.local import discover_emulator_tasks
+
+    tasks = discover_emulator_tasks(solution_dir)
+    if not tasks:
+        return
+
+    id_mapping = import_result.get("idMapping") or {}
+    console.print("\nRunning emulators...")
+
+    for task in tasks:
+        # Validate up-front so a malformed file produces a clear single warning
+        # instead of a chain of misleading downstream errors.
+        try:
+            emulator_task = EmulatorTask.model_validate(task)
+        except Exception as exc:
+            short_id = str(task.get("entityId", "<unknown>"))[:8]
+            warning(f"Invalid emulator task for {short_id}…: {exc}; skipping")
+            continue
+
+        entity_type = emulator_task.entityType
+        external_id = emulator_task.entityId
+        emulated_keys = [tp.key for tp in emulator_task.telemetryProfiles]
+
+        internal_id = id_mapping.get(external_id)
+        if not internal_id:
+            warning(f"Entity {entity_type} {external_id} not in import mapping; skipping emulator")
+            continue
+
+        try:
+            existing = set(_get_timeseries_keys(client, entity_type, internal_id))
+        except Exception as exc:
+            warning(f"Failed to fetch existing telemetry keys for {entity_type} {external_id[:8]}…: {exc}; skipping")
+            continue
+
+        overlap = sorted(set(emulated_keys) & existing)
+        if overlap and not force:
+            console.print(f"  Skipping {entity_type} {external_id[:8]}… (keys already populated: {','.join(overlap)})")
+            continue
+
+        if force and overlap:
+            try:
+                _delete_telemetry_keys(client, entity_type, internal_id, overlap)
+            except Exception as exc:
+                warning(f"Failed to delete telemetry keys for {entity_type} {external_id[:8]}…: {exc}; skipping")
+                continue
+
+        values = DeviceEmulator(emulator_task).get_values(int(time.time() * 1000))
+        path = f"/api/plugins/telemetry/{entity_type}/{internal_id}/timeseries/ANY/0"
+        try:
+            authed_request(client, "POST", path, body=values)
+        except Exception as exc:
+            warning(f"Telemetry POST failed for {entity_type} {external_id[:8]}…: {exc}")
+            continue
+        console.print(
+            f"  Emulated {entity_type} {external_id[:8]}… ({len(emulated_keys)} keys, {len(values)} datapoints)"
+        )
+
+
+def _run_reprocessing(client: Any, solution_dir: Path, import_result: dict) -> None:
+    """Execute reprocessing tasks after solution import.
+
+    Reads task files from ``tasks/reprocessing/``, resolves CF IDs via
+    the import response's ``idMapping`` and a name-based API lookup,
+    then calls ``reprocessAndWait`` for each.
+    """
+    # Lazy import to avoid circular dependency (local.py imports find_project_root)
+    from thingsboard_cli.core.local import discover_reprocessing_tasks
+
+    tasks = discover_reprocessing_tasks(solution_dir)
+    if not tasks:
+        return
+
+    id_mapping = import_result.get("idMapping") or {}
+    console.print("\nReprocessing calculated fields...")
+
+    for task in tasks:
+        entity_type = task["entityType"]
+        external_entity_id = task["entityId"]
+        cf_name = task["name"]
+        start_ts = task["startTs"]
+        end_ts = task["endTs"]
+
+        # Resolve external entity ID -> internal entity ID
+        internal_entity_id = id_mapping.get(external_entity_id)
+        if not internal_entity_id:
+            warning(
+                f"Entity {entity_type} {external_entity_id} not found in import mapping, "
+                f"skipping reprocessing for '{cf_name}'"
+            )
+            continue
+
+        # Look up the CF by internal entity ID + name. Route through
+        # ``coerce_page_kwargs`` so the int ``page_size`` / ``page`` are cast
+        # to str if the SDK signature declares them as ``Annotated[str, ...]``.
+        cf_kwargs = coerce_page_kwargs(
+            client.get_calculated_fields,
+            {
+                "entity_type": entity_type,
+                "entities": [internal_entity_id],
+                "name": [cf_name],
+                "page_size": 1,
+                "page": 0,
+            },
+        )
+        cf_page = client.get_calculated_fields(**cf_kwargs)
+        cf_list = cf_page.data or []
+        if not cf_list:
+            warning(
+                f"Calculated field '{cf_name}' not found on entity {entity_type} {internal_entity_id}, "
+                f"skipping reprocessing"
+            )
+            continue
+
+        cf_id = str(cf_list[0].id.get_id())
+        client.reprocess_calculated_field_and_wait(
+            calculated_field_id=cf_id,
+            start_ts=start_ts,
+            end_ts=end_ts,
+        )
+        console.print(f"  {cf_name} ({entity_type} {external_entity_id[:8]}...) reprocessed (completed)")
+
+
+def _load_solution_entities(solution_dir: Path) -> tuple[list[tuple[str, Path, dict]], dict]:
+    """Discover and assemble entity files, surfacing file-sourced errors cleanly.
+
+    Pydantic ``ValidationError`` raised while loading entity files is caught and
+    reformatted with ``source="file"`` so users see the "entity files" hint.
+    """
+    from pydantic import ValidationError
+
+    from thingsboard_cli.core.assembler import assemble_solution, discover_entity_files
+    from thingsboard_cli.main import _format_validation_error
+
+    try:
+        entity_files = discover_entity_files(solution_dir)
+        solution_data = assemble_solution(solution_dir)
+    except ValidationError as exc:
+        error(_format_validation_error(exc, source="file"))
+    return entity_files, solution_data
+
+
+def _display_push_counts(solution_data: dict, import_result: dict) -> None:
+    """Print per-entity-type counts after a successful import.
+
+    The server's ``SolutionImportResult`` reports only the ``created`` map
+    (entity types with zero new entities are omitted). Whatever we sent that
+    isn't accounted for there was updated, so the remainder is rendered as
+    ``updated`` using the request payload as the source of truth.
+    """
+    entities = solution_data.get("entities") or {}
+    created_raw = import_result.get("created")
+    created_bucket: dict = created_raw if isinstance(created_raw, dict) else {}
+
+    # Walk every entity type either present in the request or mentioned in
+    # the response so the listing is exhaustive, then sort into display order.
+    seen_types = _sorted_entity_types([*entities.keys(), *created_bucket.keys()])
+
+    for entity_type in seen_types:
+        request_count = len(entities.get(entity_type) or [])
+        raw_created = created_bucket.get(entity_type, 0)
+        created_count = raw_created if isinstance(raw_created, int) else 0
+        updated_count = max(request_count - created_count, 0)
+
+        parts: list[str] = []
+        if created_count:
+            parts.append(f"{created_count} created")
+        if updated_count:
+            parts.append(f"{updated_count} updated")
+        if not parts:
+            parts.append(f"{request_count} updated")
+        label = _humanize_entity_type(entity_type)
+        console.print(f"  {label:20s} {', '.join(parts)}")
+
+
+def _display_dashboard_urls(client: Any, solution_data: dict, import_result: dict) -> None:
+    """Print clickable URLs for any dashboards that were pushed.
+
+    Resolves each dashboard's server-side UUID via the import response's
+    ``idMapping``, falling back to the external ID from the solution file
+    when no mapping is present (typical for updates that reuse the target's
+    existing UUID).
+    """
+    entities = solution_data.get("entities") or {}
+    dashboards = entities.get("DASHBOARD") or []
+    if not dashboards:
+        return
+
+    id_mapping = import_result.get("idMapping") or {}
+    base_url = str(client.api_client.configuration.host or "").rstrip("/")
+
+    lines: list[tuple[str, str]] = []
+    for export in dashboards:
+        entity = (export.get("entity") if isinstance(export, dict) else None) or {}
+        ent_id = entity.get("id") or {}
+        external_id = ent_id.get("id")
+        if not external_id:
+            continue
+        internal_id = id_mapping.get(external_id) or external_id
+        title = entity.get("title") or entity.get("name") or external_id
+        url = f"{base_url}/dashboards/all/{internal_id}"
+        lines.append((str(title), url))
+
+    if not lines:
+        return
+
+    console.print("Dashboards:")
+    for title, url in lines:
+        # Title uses Rich's default link style (cyan + underline) so it stands
+        # out and is clickable via OSC 8 in modern terminals. The raw URL
+        # follows in plain text so it stays visible and copy-pasteable on
+        # terminals that don't render OSC 8 (e.g. macOS Terminal.app).
+        # Bold is intentionally avoided — on macOS Terminal.app, the default
+        # "bright bold" setting washes coloured-bold text out toward white.
+        console.print(f"  [link={url}]{escape(title)}[/link]: {url}")
+
+
+def push_command(
+    ctx: typer.Context,
+    targets: Annotated[
+        list[str] | None,
+        typer.Argument(help="Solution name (default: all root entities)"),
+    ] = None,
+    profile: ProfileOption = None,
+    push_all: bool = typer.Option(False, "--all", help="Push root + all solutions"),
+    skip_validate: bool = typer.Option(False, "--skip-validate", help="Skip validation before push"),
+    run_tasks: bool = typer.Option(False, "--run-tasks", help="Run post-import tasks (e.g. CF reprocessing)"),
+    force_emulators: bool = typer.Option(
+        False,
+        "--force-emulators",
+        help=(
+            "Regenerate emulator telemetry even when emulated keys already have data. "
+            "DELETES the overlapping keys on the target before posting fresh data. "
+            "Requires --run-tasks; pair with --yes to skip the confirm prompt."
+        ),
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip confirmation prompts for any destructive push-time action (e.g. --force-emulators).",
+    ),
+) -> None:
+    """Push local resource definitions to ThingsBoard via Solution Import."""
+    if force_emulators and not run_tasks:
+        error("`--force-emulators` requires `--run-tasks`.")
+
+    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=profile)
+    client = build_client(resolved)
+
+    dirs_to_push = _resolve_solution_dirs(project_root, targets, push_all)
+
+    if run_tasks and force_emulators and not yes:
+        typer.confirm(
+            "--force-emulators will DELETE telemetry for emulated keys on the target. Continue?",
+            abort=True,
+        )
+
+    for label, solution_dir in dirs_to_push:
+        entity_files, solution_data = _load_solution_entities(solution_dir)
+        if not entity_files:
+            if len(dirs_to_push) == 1:
+                console.print("No entities to push.")
+            continue
+
+        total = _local_entity_count(solution_data)
+
+        if len(dirs_to_push) > 1:
+            console.print(f"\n[bold]Pushing {escape(label)}[/bold] ({pluralize(total, 'entity', 'entities')})")
+
+        # Validate before push unless skipped. On success, skip the per-type
+        # breakdown — the post-import counts cover it. On failure, the full
+        # breakdown is preserved so users can see what was checked.
+        if not skip_validate and not _validate_and_display(client, solution_data, brief_when_valid=True):
+            error("Validation failed. Fix the issues above or use --skip-validate to push anyway.")
+
+        result = _rest_post(client, "/api/solution/import", solution_data)
+
+        if len(dirs_to_push) == 1:
+            console.print(f"Pushed solution ({pluralize(total, 'entity', 'entities')})")
+
+        _display_push_counts(solution_data, result)
+        _display_dashboard_urls(client, solution_data, result)
+
+        if run_tasks:
+            _run_emulators(client, solution_dir, result, force=force_emulators)
+            _run_reprocessing(client, solution_dir, result)
+
+
+def validate_command(
+    ctx: typer.Context,
+    targets: Annotated[
+        list[str] | None,
+        typer.Argument(help="Solution name (default: all root-level entities)"),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """Validate local resource definitions against ThingsBoard (dry-run)."""
+    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=profile)
+    client = build_client(resolved)
+
+    dirs_to_validate = _resolve_solution_dirs(project_root, targets)
+
+    all_valid = True
+    for label, solution_dir in dirs_to_validate:
+        entity_files, solution_data = _load_solution_entities(solution_dir)
+        if not entity_files:
+            if len(dirs_to_validate) == 1:
+                console.print("No entities to validate.")
+            continue
+
+        if len(dirs_to_validate) > 1:
+            console.print(f"\n[bold]{escape(label)}[/bold]")
+
+        if not _validate_and_display(client, solution_data):
+            all_valid = False
+
+    if not all_valid:
+        raise typer.Exit(1)