thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/core/local.py

@@ -0,0 +1,1080 @@
+"""Local mode utilities for IaC-style project management."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+import time
+import unicodedata
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+import typer
+from filelock import FileLock
+
+from thingsboard_cli.commands.project import find_project_root
+
+# ---------------------------------------------------------------------------
+# Concurrency primitives
+# ---------------------------------------------------------------------------
+
+# Soft cap for how long a writer is willing to wait on the per-entity lock
+# before giving up. Five seconds comfortably absorbs realistic parallel
+# subagent contention while still surfacing genuine hangs.
+LOCK_TIMEOUT_SECONDS: float = 5.0
+
+
+def atomic_write_text(path: Path, content: str) -> None:
+    """Write *content* to *path* atomically.
+
+    Writes to a sibling temp file, fsyncs, then ``os.replace``s onto the
+    final path. ``os.replace`` is atomic on POSIX and on Windows (Python
+    3.3+), so an interrupted call leaves either the pre-existing file
+    or the new content in full — never a truncated mix.
+    """
+    fd, tmp_name = tempfile.mkstemp(
+        dir=str(path.parent),
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_name, path)
+    except BaseException:
+        Path(tmp_name).unlink(missing_ok=True)
+        raise
+
+
+def _locks_dir(solution_dir: Path) -> Path:
+    """Return the per-solution ``.locks/`` directory, creating it lazily.
+
+    First-time creation drops a ``.gitignore: *\\n`` so the lock files are
+    invisible to ``git status`` without touching the user's root
+    ``.gitignore``.
+    """
+    d = solution_dir / ".locks"
+    if not d.exists():
+        d.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(d / ".gitignore", "*\n")
+    return d
+
+
+# Pattern of characters that are NOT safe to interpolate into a filelock
+# filename. We allow ASCII alphanumerics plus ``.``, ``_`` and ``-``. Anything
+# else (``/``, ``\``, ``..``, whitespace, NUL, control bytes, unicode, …) is
+# collapsed to ``_`` before we build the lock path so a caller-supplied
+# ``entity_id`` or task ``key`` cannot escape ``.locks/``.
+_LOCK_KEY_UNSAFE = re.compile(r"[^A-Za-z0-9._-]")
+
+
+def _safe_lock_key(raw: str) -> str:
+    """Sanitize an entity-ID / task-key for safe use as a lock filename.
+
+    Replaces every character outside ``[A-Za-z0-9._-]`` with ``_`` and
+    falls back to ``"_"`` for the empty string. UUIDs (the common case)
+    round-trip unchanged.
+
+    Note: this is a one-way mapping. Two raw keys that contain different
+    unsafe characters can sanitize to the same lock filename
+    (e.g. ``"a/b"`` and ``"a\\b"`` both become ``"a_b"``). In practice
+    entity IDs are server-issued UUIDs and won't collide; the collision
+    risk only matters if a future caller starts feeding free-form keys
+    into ``entity_lock``/``task_lock``. The downside of a collision is
+    spurious extra serialization, not data loss.
+    """
+    cleaned = _LOCK_KEY_UNSAFE.sub("_", raw)
+    return cleaned or "_"
+
+
+@contextmanager
+def entity_lock(solution_dir: Path, entity_id: str, *, timeout: float | None = None) -> Iterator[None]:
+    """Serialize all writes against a single entity (by entity-ID).
+
+    Keyed on the stable entity ID (not the on-disk slug) so a rename and
+    a concurrent embed against the same entity still serialize cleanly.
+    Backed by ``filelock.FileLock`` — ``fcntl.flock`` on POSIX,
+    ``msvcrt.locking`` on Windows. The OS releases the lock on process
+    death.
+
+    The *entity_id* is sanitized via :func:`_safe_lock_key` before being
+    interpolated into the lock filename, so a malicious or accidentally
+    path-traversal-y ID (``"../../escaped"``) can't drop the lock file
+    outside ``.locks/``.
+
+    When *timeout* is ``None``, ``LOCK_TIMEOUT_SECONDS`` is consulted at
+    call-time so tests can monkeypatch the module-level constant to
+    shorten the wait.
+    """
+    effective = timeout if timeout is not None else LOCK_TIMEOUT_SECONDS
+    safe_key = _safe_lock_key(entity_id)
+    lock = FileLock(str(_locks_dir(solution_dir) / f"{safe_key}.lock"), timeout=effective)
+    with lock:
+        yield
+
+
+@contextmanager
+def task_lock(solution_dir: Path, key: str, *, timeout: float | None = None) -> Iterator[None]:
+    """Serialize writes against a non-entity-keyed task file (emulator, reprocessing).
+
+    The *key* is sanitized via :func:`_safe_lock_key` before being used as
+    a filename — see :func:`entity_lock` for rationale. See
+    :func:`entity_lock` for the *timeout* contract.
+    """
+    effective = timeout if timeout is not None else LOCK_TIMEOUT_SECONDS
+    safe_key = _safe_lock_key(key)
+    lock = FileLock(str(_locks_dir(solution_dir) / f"{safe_key}.lock"), timeout=effective)
+    with lock:
+        yield
+
+
+class LocalEntityNotFoundError(Exception):
+    """Raised when a local entity file lookup fails.
+
+    Carries *entity_type* / *entity_id* on the exception so command-layer
+    handlers can render a consistent, solution-relative error message
+    regardless of whether the file was missing up-front or vanished
+    between a pre-check and the locked re-check.
+    """
+
+    def __init__(self, entity_type: str, entity_id: str) -> None:
+        self.entity_type = entity_type
+        self.entity_id = entity_id
+        super().__init__(f"{entity_type} {entity_id} not found in local files")
+
+
+# Maps ThingsBoard entity types to local directory names.
+ENTITY_DIR_MAP: dict[str, str] = {
+    "CUSTOMER": "customers",
+    "ROLE": "roles",
+    "ENTITY_GROUP": "entity-groups",
+    "RULE_CHAIN": "rule-chains",
+    "DASHBOARD": "dashboards",
+    "ASSET_PROFILE": "asset-profiles",
+    "ASSET": "assets",
+    "DEVICE_PROFILE": "device-profiles",
+    "DEVICE": "devices",
+    "USER": "users",
+}
+
+# Entity types where the display name comes from 'title' instead of 'name'.
+_TITLE_ENTITIES = {"DASHBOARD", "CUSTOMER"}
+
+# Entity types where the display name comes from 'email'.
+_EMAIL_ENTITIES = {"USER"}
+
+
+# Maximum slug length used in on-disk filenames. The composed filename is
+# ``<slug>-<uuid>.json`` plus an ``atomic_write_text`` temp prefix of
+# ``.<name>.XXXXXX.tmp``; budget is ~255 bytes on Linux ext4 and ~260
+# (full path) on Windows. 100 leaves comfortable headroom for both the
+# UUID suffix and deeply nested solution trees.
+_SLUG_MAX_LENGTH = 100
+
+
+def slugify(text: str, *, max_length: int = _SLUG_MAX_LENGTH) -> str:
+    """Convert text to a kebab-case filename slug.
+
+    Strips accents, lowercases, replaces non-alphanumeric characters with
+    hyphens, collapses consecutive hyphens, and caps the result at
+    *max_length* characters so the slug stays comfortably under
+    filesystem filename limits when combined with the entity UUID suffix.
+    """
+    if not text:
+        return ""
+    # Decompose unicode and strip combining marks (accents)
+    text = unicodedata.normalize("NFKD", text)
+    text = "".join(c for c in text if not unicodedata.combining(c))
+    text = text.lower()
+    # Replace any non-alphanumeric character with a hyphen
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    # Strip leading/trailing hyphens
+    text = text.strip("-")
+    if len(text) > max_length:
+        # Truncate, then re-strip in case the cut landed on a hyphen.
+        text = text[:max_length].rstrip("-")
+    return text
+
+
+def read_project_config() -> dict | None:
+    """Read thingsboard.json from the project root.
+
+    Returns the parsed dict, or None if no project root is found or the
+    file contains invalid JSON.
+    """
+    project_root = find_project_root()
+    if project_root is None:
+        return None
+    config_path = project_root / "thingsboard.json"
+    try:
+        return json.loads(config_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def is_local_mode() -> bool:
+    """Return True only when thingsboard.json has ``"mode": "local"``."""
+    config = read_project_config()
+    if config is None:
+        return False
+    return config.get("mode") == "local"
+
+
+# ---------------------------------------------------------------------------
+# Extension name (extension.name in thingsboard.json)
+# ---------------------------------------------------------------------------
+
+# Max length matches the docker image-reference name component soft cap.
+# Anything longer is awkward to type, awkward in `docker images` output, and
+# pushes past the conservative end of common registry name limits.
+_EXTENSION_NAME_MAX_LENGTH = 128
+
+# Allowed characters mirror the docker image-reference name component:
+# lowercase ASCII letters, digits, dashes, underscores, periods. Slashes
+# are *deliberately* excluded — they denote registry/org prefixes, which
+# belong on the push target, not on the local manifest name.
+# Use ``\Z`` rather than ``$`` so a trailing ``\n`` does not slip through —
+# in Python regex, ``$`` matches *before* a final newline.
+_EXTENSION_NAME_BODY_PATTERN = re.compile(r"\A[a-z0-9._-]+\Z")
+_EXTENSION_NAME_FIRST_CHAR_PATTERN = re.compile(r"\A[a-z0-9]")
+
+
+class ExtensionNameError(ValueError):
+    """Raised when an extension name fails validation or the manifest is malformed."""
+
+
+def validate_extension_name(name: str) -> None:
+    """Validate *name* against the extension-name rules.
+
+    Returns ``None`` on success; raises :class:`ExtensionNameError` with a
+    user-facing message identifying the violated rule otherwise.
+
+    Rules (matching the docker image-reference name component):
+
+    - non-empty, at most ``_EXTENSION_NAME_MAX_LENGTH`` (128) characters
+    - lowercase ASCII letters, digits, dashes (``-``), underscores (``_``),
+      periods (``.``)
+    - must start with a letter or digit
+    - must not contain slashes (slashes belong on the push target, not the
+      local name)
+
+    The validator is strict: it does *not* trim whitespace. Callers that read
+    from an interactive prompt should ``.strip()`` the input first.
+    """
+    if not name:
+        msg = "Extension name must not be empty."
+        raise ExtensionNameError(msg)
+    if len(name) > _EXTENSION_NAME_MAX_LENGTH:
+        msg = f"Extension name must be at most {_EXTENSION_NAME_MAX_LENGTH} characters (got {len(name)})."
+        raise ExtensionNameError(msg)
+    if "/" in name:
+        msg = "Extension name must not contain slashes — slashes belong on the push target, not the local name."
+        raise ExtensionNameError(msg)
+    if not _EXTENSION_NAME_BODY_PATTERN.match(name):
+        msg = (
+            "Extension name can only contain lowercase letters, digits, dashes, underscores, and periods "
+            f"(got {name!r})."
+        )
+        raise ExtensionNameError(msg)
+    if not _EXTENSION_NAME_FIRST_CHAR_PATTERN.match(name):
+        msg = f"Extension name must start with a letter or digit (got {name!r})."
+        raise ExtensionNameError(msg)
+
+
+def read_extension_name(project_root: Path) -> str | None:
+    """Return ``extension.name`` from *project_root*'s ``thingsboard.json``.
+
+    Returns ``None`` when the manifest is missing, unreadable, malformed
+    JSON, has no ``extension`` block, has no ``name`` field, or any of
+    these is not the expected type (top-level not an object, ``extension``
+    not an object, ``name`` not a string). The value is returned verbatim
+    — this is the read side, so callers decide whether to validate stale
+    on-disk values.
+    """
+    manifest_path = project_root / "thingsboard.json"
+    try:
+        data = json.loads(manifest_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    extension = data.get("extension")
+    if not isinstance(extension, dict):
+        return None
+    name = extension.get("name")
+    if not isinstance(name, str):
+        return None
+    return name
+
+
+def diagnose_extension_name(project_root: Path) -> str | None:
+    """Return ``extension.name`` from the manifest, or raise on malformed manifest.
+
+    Like :func:`read_extension_name`, but distinguishes a malformed/non-object
+    manifest from a valid manifest with no ``extension.name`` set. Callers that
+    only need "is the name set?" can use :func:`read_extension_name`; commands
+    that want to point the user at the real problem (a hand-broken JSON file vs
+    a missing field) should use this and surface the raised message instead of
+    a generic "set the name" hint.
+
+    Returns:
+        The extension name string when the manifest is well-formed and the
+        field is set. ``None`` when the manifest is missing, the ``extension``
+        block is missing/not-a-dict, or ``name`` is missing/not-a-string.
+
+    Raises:
+        ExtensionNameError: When ``thingsboard.json`` exists but is unreadable,
+            invalid JSON, or whose top-level value is not a JSON object.
+    """
+    manifest_path = project_root / "thingsboard.json"
+    if not manifest_path.exists():
+        return None
+    try:
+        raw = manifest_path.read_text()
+    except OSError as exc:
+        msg = f"thingsboard.json could not be read: {exc}"
+        raise ExtensionNameError(msg) from None
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        msg = "thingsboard.json is malformed or not a JSON object — fix the file before running this command."
+        raise ExtensionNameError(msg) from None
+    if not isinstance(data, dict):
+        msg = "thingsboard.json is malformed or not a JSON object — fix the file before running this command."
+        raise ExtensionNameError(msg)
+    extension = data.get("extension")
+    if not isinstance(extension, dict):
+        return None
+    name = extension.get("name")
+    if not isinstance(name, str):
+        return None
+    return name
+
+
+def write_extension_name(project_root: Path, name: str) -> None:
+    """Set ``extension.name`` in ``thingsboard.json`` under *project_root*.
+
+    Validates *name* before touching disk so an invalid input never leaves
+    the manifest in a partial state. Creates the manifest with ``{}`` if
+    absent, and creates the ``extension`` sub-object if absent. Preserves
+    all other top-level keys, their order, and any other keys inside the
+    ``extension`` block. Writes atomically via :func:`atomic_write_text`.
+
+    Raises :class:`ExtensionNameError` if *name* fails validation, or if
+    the existing manifest is malformed JSON (in which case the file is
+    left untouched — we refuse to silently overwrite a hand-edited file
+    the user might still be salvaging).
+    """
+    validate_extension_name(name)
+
+    manifest_path = project_root / "thingsboard.json"
+    data: dict
+    if manifest_path.exists():
+        try:
+            raw = manifest_path.read_text()
+        except OSError as exc:
+            msg = f"thingsboard.json could not be read: {exc}"
+            raise ExtensionNameError(msg) from None
+        try:
+            loaded = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            msg = f"thingsboard.json is malformed: {exc}"
+            raise ExtensionNameError(msg) from None
+        if not isinstance(loaded, dict):
+            msg = "thingsboard.json must contain a JSON object at the top level."
+            raise ExtensionNameError(msg)
+        data = loaded
+    else:
+        data = {}
+
+    extension = data.get("extension")
+    if not isinstance(extension, dict):
+        extension = {}
+    extension["name"] = name
+    data["extension"] = extension
+
+    atomic_write_text(manifest_path, json.dumps(data, indent=2) + "\n")
+
+
+def resolve_solution_dir(project_root: Path | None, solution_name: str | None = None) -> Path:
+    """Return the solution directory for a given project root.
+
+    If *solution_name* is provided, returns ``project_root/solutions/<name>/``.
+    Otherwise, if cwd is inside ``project_root/solutions/<name>/``, returns
+    that solution directory automatically.
+    Falls back to *project_root* itself.
+
+    Raises ``typer.Exit`` if *project_root* is ``None``.
+    """
+    if project_root is None:
+        from thingsboard_cli.core.output import error
+
+        error("Not a ThingsBoard project. Run 'tb init' first.")
+        raise typer.Exit(code=1)
+    if solution_name:
+        return project_root / "solutions" / solution_name
+    # Auto-detect: if cwd is inside solutions/<name>/, use that solution
+    try:
+        cwd = Path.cwd().resolve()
+        solutions_dir = (project_root / "solutions").resolve()
+        rel = cwd.relative_to(solutions_dir)
+        # First component of the relative path is the solution name
+        detected = rel.parts[0] if rel.parts else None
+        if detected:
+            return project_root / "solutions" / detected
+    except (ValueError, IndexError):
+        pass
+    return project_root
+
+
+# ---------------------------------------------------------------------------
+# Model-based validation (uses tb-pe-client Pydantic models)
+# ---------------------------------------------------------------------------
+
+# Maps entity types to their tb-pe-client model module and class name.
+_ENTITY_MODEL_MAP: dict[str, tuple[str, str]] = {
+    "ASSET": ("tb_pe_client.models.asset", "Asset"),
+    "ASSET_PROFILE": ("tb_pe_client.models.asset_profile", "AssetProfile"),
+    "CUSTOMER": ("tb_pe_client.models.customer", "Customer"),
+    "DASHBOARD": ("tb_pe_client.models.dashboard", "Dashboard"),
+    "DEVICE": ("tb_pe_client.models.device", "Device"),
+    "DEVICE_PROFILE": ("tb_pe_client.models.device_profile", "DeviceProfile"),
+    "ENTITY_GROUP": ("tb_pe_client.models.entity_group", "EntityGroup"),
+    "ROLE": ("tb_pe_client.models.role", "Role"),
+    "RULE_CHAIN": ("tb_pe_client.models.rule_chain", "RuleChain"),
+    "USER": ("tb_pe_client.models.user", "User"),
+}
+
+# Maps embed field names to (module, class, user-facing label).
+_EMBED_MODEL_MAP: dict[str, tuple[str, str, str]] = {
+    "relations": ("tb_pe_client.models.entity_relation", "EntityRelation", "relation"),
+    "calculatedFields": ("tb_pe_client.models.calculated_field", "CalculatedField", "calculated field"),
+}
+
+
+def _snake_to_camel(name: str) -> str:
+    """Convert a snake_case name to camelCase for user-facing messages."""
+    parts = name.split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def _format_field_path(loc: tuple) -> str:
+    """Format a Pydantic error location into a camelCase dotted path."""
+    parts: list[str] = []
+    for p in loc:
+        if isinstance(p, int):
+            parts.append(f"[{p}]")
+        else:
+            parts.append(_snake_to_camel(str(p)))
+    return ".".join(parts)
+
+
+def _validate_with_model(module_path: str, class_name: str, data: dict, *, label: str | None = None) -> None:
+    """Validate *data* by constructing a tb-pe-client model via ``from_dict``.
+
+    Raises ``ValueError`` with a user-friendly message on failure.
+    *label* is the user-facing name shown in the error (e.g. "alarm rule").
+    Falls back to *class_name* if not provided.
+    """
+    from importlib import import_module
+
+    display_name = label or class_name
+
+    try:
+        mod = import_module(module_path)
+        cls = getattr(mod, class_name)
+        cls.from_dict(data)
+    except Exception as exc:
+        if not hasattr(exc, "errors"):
+            raise ValueError(f"Invalid {display_name}: {exc}") from None
+
+        errors = exc.errors()
+        lines = [f"Validation failed for {display_name}:"]
+        for err in errors:
+            field_path = _format_field_path(err.get("loc", ()))
+            input_val = err.get("input", None)
+            msg = err.get("msg", "unknown error")
+            hint = f"  {field_path}: {msg}"
+            if input_val is not None:
+                hint += f" (got {type(input_val).__name__}: {input_val!r})"
+            lines.append(hint)
+        raise ValueError("\n".join(lines)) from None
+
+
+def validate_entity(entity_type: str, data: dict) -> None:
+    """Validate entity data against tb-pe-client model before saving locally."""
+    model_info = _ENTITY_MODEL_MAP.get(entity_type)
+    if model_info:
+        _validate_with_model(model_info[0], model_info[1], data)
+
+
+def validate_embedded(field_name: str, data: dict, *, label: str | None = None) -> None:
+    """Validate embedded data (relation, calculated field) against its model."""
+    model_info = _EMBED_MODEL_MAP.get(field_name)
+    if model_info:
+        _validate_with_model(model_info[0], model_info[1], data, label=label or model_info[2])
+
+
+def get_name_field(entity_type: str) -> str:
+    """Return the JSON field used as the human-readable name for an entity type."""
+    if entity_type in _TITLE_ENTITIES:
+        return "title"
+    if entity_type in _EMAIL_ENTITIES:
+        return "email"
+    return "name"
+
+
+def save_entity_file(
+    solution_dir: Path,
+    entity_type: str,
+    data: dict,
+    *,
+    existing_path_to_replace: Path | None = None,
+    extras: dict | None = None,
+) -> Path:
+    """Write entity JSON to the correct directory under *solution_dir*.
+
+    *data* is plain entity JSON (e.g. ``{"name": "sensor-1", "id": {...}}``).
+    It is wrapped in EntityExportData format before writing.
+
+    The entity object must contain an ``id`` field and an appropriate name
+    field (``name``, ``title``, or ``email`` depending on the entity type).
+
+    *extras* carries any sibling fields from a server-returned
+    ``EntityExportData`` (``credentials``, ``relations``, ``attributes``,
+    ``calculatedFields``, ``permissions``, …). They are emitted alongside
+    ``entityType`` and ``entity`` so the on-disk wrapper is byte-symmetric
+    with what ``tb push`` ships back to ``/api/solution/import``. Reserved
+    keys (``entityType``, ``entity``) inside *extras* are dropped.
+
+    When *existing_path_to_replace* is provided and resolves to a different
+    location than the newly-computed path, the new file is written first
+    and only then is the old file unlinked. Crashing mid-call therefore
+    leaves a duplicate on disk rather than a hole — git surfaces the rename
+    naturally on the next status. If the old and new paths resolve to the
+    same location (entity slug didn't change), this collapses to a plain
+    overwrite. A missing old file is silently tolerated (``missing_ok``).
+
+    When *existing_path_to_replace* is ``None`` and a file for this
+    ``entity.id.id`` already exists in the entity directory, that file is
+    discovered and treated as the rename target. This means a CRUD-style
+    ``tb <type> save --json`` that changes the display name cleans up the
+    previous-name file instead of leaving a silent orphan that would later
+    trip the duplicate-external-ID guard in ``tb pull``.
+
+    Returns the path to the written file.
+
+    Raises:
+        ValueError: If *entity_type* is unknown, or if required fields
+            are missing from *data*.
+    """
+    if entity_type not in ENTITY_DIR_MAP:
+        msg = f"Unknown entity type: {entity_type}"
+        raise ValueError(msg)
+
+    if not data.get("id"):
+        msg = "Entity data missing required 'id' field"
+        raise ValueError(msg)
+
+    name_field = get_name_field(entity_type)
+    name_value = data.get(name_field)
+    if not name_value:
+        msg = f"Entity data missing required '{name_field}' field"
+        raise ValueError(msg)
+
+    validate_entity(entity_type, data)
+
+    dir_name = ENTITY_DIR_MAP[entity_type]
+    entity_dir = solution_dir / dir_name
+    entity_dir.mkdir(parents=True, exist_ok=True)
+
+    export_data: dict = {"entityType": entity_type, "entity": data}
+    if extras:
+        for key, value in extras.items():
+            if key in ("entityType", "entity"):
+                continue
+            export_data[key] = value
+
+    # Lock on the stable entity id (entity.id.id) so concurrent saves of
+    # the same entity serialize cleanly even when they target different
+    # slugs (rename) or when an unrelated embed (cf save / alarm-rule
+    # save / attributes save) is mutating the same file via a different
+    # path. On pulled entities this id and the server-side ``externalId``
+    # carry the same value — the server substitutes id to the external
+    # UUID on export — but locally we always key off ``entity.id.id``.
+    entity_id_str = str(data["id"].get("id") if isinstance(data["id"], dict) else data["id"])
+    # Append the entity id to the filename so two entities with the same
+    # display name (e.g. an "All Devices" entity-group per customer) don't
+    # collide on disk. The slug prefix keeps filenames human-scannable.
+    filename = f"{slugify(name_value)}-{entity_id_str}.json"
+    file_path = entity_dir / filename
+    with entity_lock(solution_dir, entity_id_str):
+        # When no explicit rename target was provided, look one up by
+        # entity id so a display-name change cleans up the previous-name
+        # file instead of leaving a silent orphan. Must run inside the
+        # lock so a concurrent rename of the same entity can't race us
+        # into a stale path.
+        if existing_path_to_replace is None:
+            found = _find_local_entity_file(solution_dir, entity_type, entity_id_str)
+            if found is not None:
+                existing_path_to_replace = found[0]
+
+        atomic_write_text(file_path, json.dumps(export_data, indent=4) + "\n")
+
+        # Resolve both sides so a relative-vs-absolute mismatch doesn't
+        # cause us to delete the file we just wrote. ``Path.resolve`` is
+        # non-strict by default and tolerates missing files.
+        if existing_path_to_replace is not None and existing_path_to_replace.resolve() != file_path.resolve():
+            existing_path_to_replace.unlink(missing_ok=True)
+
+    return file_path
+
+
+def embed_in_parent_entity(
+    solution_dir: Path,
+    parent_entity_id: dict,
+    field_name: str,
+    item_data: dict,
+    *,
+    label: str | None = None,
+) -> Path:
+    """Embed an item (calculated field, alarm rule, etc.) in a parent entity's export data.
+
+    Finds the parent entity file by type and ID, then appends *item_data*
+    to the *field_name* array.  If an item with the same ``id`` already
+    exists in the array it is replaced instead of duplicated.
+
+    Returns the path to the updated parent entity file.
+
+    Raises:
+        ValueError: If the parent entity type is unknown or the parent
+            entity file is not found in the solution directory.
+    """
+    validate_embedded(field_name, item_data, label=label)
+
+    entity_type = parent_entity_id.get("entityType") or parent_entity_id.get("entity_type")
+    entity_id = parent_entity_id.get("id")
+
+    # Validate the parent reference BEFORE acquiring the lock so a junk
+    # entity_type / missing ID doesn't briefly create a sanitized-to-"_"
+    # lock file on disk.
+    if entity_type not in ENTITY_DIR_MAP:
+        msg = f"Unknown entity type: {entity_type}"
+        raise ValueError(msg)
+    if not entity_id:
+        msg = "Parent entity reference is missing an 'id' field"
+        raise ValueError(msg)
+
+    entity_id_str = str(entity_id)
+
+    # The file lookup happens INSIDE the lock so a concurrent
+    # ``save_entity_file`` rename can't move the file between our lookup
+    # and our write.
+    with entity_lock(solution_dir, entity_id_str):
+        found = _find_local_entity_file(solution_dir, entity_type, entity_id_str)
+        if found is None:
+            msg = f"Parent entity {entity_type} {entity_id} not found in solution. Save the parent entity first."
+            raise ValueError(msg)
+        parent_file, parent_data = found
+
+        # Get or create the array
+        items = parent_data.setdefault(field_name, [])
+
+        # Check for existing item with same ID (replace if found)
+        item_id = item_data.get("id", {})
+        item_id_str = item_id.get("id") if isinstance(item_id, dict) else None
+        if item_id_str:
+            for i, existing in enumerate(items):
+                existing_id = existing.get("id", {})
+                if isinstance(existing_id, dict) and existing_id.get("id") == item_id_str:
+                    items[i] = item_data
+                    atomic_write_text(parent_file, json.dumps(parent_data, indent=4) + "\n")
+                    return parent_file
+
+        items.append(item_data)
+        atomic_write_text(parent_file, json.dumps(parent_data, indent=4) + "\n")
+        return parent_file
+
+
+DEFAULT_REPROCESSING_ORDER = 100
+
+
+def save_reprocessing_task(
+    solution_dir: Path,
+    *,
+    entity_type: str,
+    entity_id: str,
+    name: str,
+    start_ts: int,
+    end_ts: int,
+    order: int = DEFAULT_REPROCESSING_ORDER,
+) -> Path:
+    """Save a calculated field reprocessing task to disk.
+
+    Creates ``tasks/reprocessing/<entity-id-prefix>-<slugified-name>.json``.
+    Overwrites if a file for the same entity + CF name already exists.
+
+    *order* controls the execution sequence during ``tb push --run-tasks``:
+    tasks with a lower ``order`` run first; ties are broken by file name.
+
+    Returns the path to the written file.
+    """
+    task_dir = solution_dir / "tasks" / "reprocessing"
+    task_dir.mkdir(parents=True, exist_ok=True)
+
+    entity_prefix = entity_id[:8]
+    filename = f"{entity_prefix}-{slugify(name)}.json"
+    task_data = {
+        "entityType": entity_type,
+        "entityId": entity_id,
+        "name": name,
+        "startTs": start_ts,
+        "endTs": end_ts,
+        "order": order,
+    }
+    file_path = task_dir / filename
+    with task_lock(solution_dir, f"reprocess-{entity_id}-{slugify(name)}"):
+        atomic_write_text(file_path, json.dumps(task_data, indent=4) + "\n")
+    return file_path
+
+
+def discover_reprocessing_tasks(solution_dir: Path) -> list[dict]:
+    """Discover all reprocessing task files in ``tasks/reprocessing/``.
+
+    Returns a list of parsed task dicts sorted by ``(order, name)``. Files
+    without an explicit ``order`` get :data:`DEFAULT_REPROCESSING_ORDER`.
+    Skips files with invalid JSON.
+    """
+    task_dir = solution_dir / "tasks" / "reprocessing"
+    if not task_dir.is_dir():
+        return []
+
+    tasks: list[dict] = []
+    for json_file in sorted(task_dir.glob("*.json")):
+        try:
+            data = json.loads(json_file.read_text())
+        except json.JSONDecodeError:
+            continue
+        tasks.append(data)
+    tasks.sort(key=lambda t: (t.get("order", DEFAULT_REPROCESSING_ORDER), t.get("name", "")))
+    return tasks
+
+
+# ---------------------------------------------------------------------------
+# Emulator tasks
+# ---------------------------------------------------------------------------
+
+
+def save_emulator_task(
+    solution_dir: Path,
+    *,
+    entity_type: str,
+    entity_id: str,
+    telemetry_profiles: list[dict],
+    days: int,
+    interval_ms: int,
+) -> Path:
+    """Save a telemetry-emulator task to disk.
+
+    Creates ``tasks/emulators/<entity-id-prefix>-emulator.json`` for the
+    common case. If another task already occupies the prefix slot but
+    targets a *different* entity (8-char UUID prefix collision — extremely
+    rare but possible), falls back to a longer-prefix filename to avoid
+    silently overwriting an unrelated emulator.
+
+    Returns the path to the written file.
+    """
+    task_dir = solution_dir / "tasks" / "emulators"
+    task_dir.mkdir(parents=True, exist_ok=True)
+
+    task_data = {
+        "entityType": entity_type,
+        "entityId": entity_id,
+        "telemetryProfiles": telemetry_profiles,
+        "days": days,
+        "intervalMs": interval_ms,
+    }
+
+    # The check-then-act (prefix collision) and the write must both happen
+    # under the same lock; otherwise two concurrent ``emulator add`` for the
+    # same entity can race past the collision check and both write into the
+    # same prefix slot.
+    with task_lock(solution_dir, f"emul-{entity_id}"):
+        file_path = task_dir / f"{entity_id[:8]}-emulator.json"
+        if file_path.is_file():
+            try:
+                existing = json.loads(file_path.read_text())
+            except json.JSONDecodeError:
+                existing = {}
+            if existing.get("entityId") and existing.get("entityId") != entity_id:
+                # Prefix collision with a different entity — extend the prefix.
+                file_path = task_dir / f"{entity_id[:16]}-emulator.json"
+
+        atomic_write_text(file_path, json.dumps(task_data, indent=4) + "\n")
+    return file_path
+
+
+def discover_emulator_tasks(solution_dir: Path) -> list[dict]:
+    """Discover all emulator task files in ``tasks/emulators/``.
+
+    Returns a list of parsed task dicts. Skips files with invalid JSON.
+    Files are returned in stable filename order so push output is deterministic.
+    """
+    task_dir = solution_dir / "tasks" / "emulators"
+    if not task_dir.is_dir():
+        return []
+
+    tasks: list[dict] = []
+    for json_file in sorted(task_dir.glob("*.json")):
+        try:
+            data = json.loads(json_file.read_text())
+        except json.JSONDecodeError:
+            continue
+        tasks.append(data)
+    return tasks
+
+
+def delete_emulator_task(solution_dir: Path, *, entity_id: str) -> Path | None:
+    """Delete the emulator task file for *entity_id* if it exists.
+
+    Verifies that the file's stored ``entityId`` matches *entity_id* before
+    unlinking, so a UUID-prefix collision with another emulator can't
+    silently delete the wrong file. Returns the deleted path, or None if
+    no matching file existed (idempotent).
+    """
+    task_dir = solution_dir / "tasks" / "emulators"
+    if not task_dir.is_dir():
+        return None
+    # Take the same lock ``save_emulator_task`` uses so the verify+unlink
+    # can't race against a concurrent write that just landed on this slot.
+    with task_lock(solution_dir, f"emul-{entity_id}"):
+        for json_file in task_dir.glob("*-emulator.json"):
+            try:
+                data = json.loads(json_file.read_text())
+            except json.JSONDecodeError:
+                continue
+            if data.get("entityId") == entity_id:
+                json_file.unlink()
+                return json_file
+    return None
+
+
+def _find_local_entity_file(solution_dir: Path, entity_type: str, entity_id: str) -> tuple[Path, dict] | None:
+    """Locate the export-data file for *entity_id* and return (path, parsed_dict).
+
+    Walks ``solution_dir/<entity-dir>/*.json`` for a file whose
+    ``entity.id.id`` matches. Returns ``None`` when the directory is
+    missing or no file matches. Shared by :func:`find_local_entity` and
+    :func:`add_member_ids_to_local_group` so both stay in lockstep on
+    how a "local entity" is located.
+    """
+    if entity_type not in ENTITY_DIR_MAP:
+        return None
+    entity_dir = solution_dir / ENTITY_DIR_MAP[entity_type]
+    if not entity_dir.is_dir():
+        return None
+    for json_file in entity_dir.glob("*.json"):
+        try:
+            data = json.loads(json_file.read_text())
+        except json.JSONDecodeError:
+            continue
+        eid = data.get("entity", {}).get("id", {})
+        if isinstance(eid, dict) and eid.get("id") == entity_id:
+            return json_file, data
+    return None
+
+
+def add_member_ids_to_local_group(
+    solution_dir: Path,
+    entity_group_id: str,
+    entity_ids: list[str],
+) -> tuple[Path, int]:
+    """Append member UUIDs to a local entity-group export file's ``memberIds``.
+
+    Finds the entity-group file under ``solution_dir/entity-groups/`` whose
+    ``entity.id.id`` matches *entity_group_id*. Member IDs are stored on
+    the ``EntityGroupExportData`` wrapper (top-level, not nested under
+    ``entity``) per the TB import schema. The list is initialized if absent.
+
+    New IDs are appended in input order; IDs already present (in the
+    existing list or earlier in *entity_ids*) are dropped to keep
+    ``memberIds`` deduplicated.
+
+    Returns ``(file_path, added_count)`` where ``added_count`` is the
+    number of IDs that were actually written (excludes duplicates).
+
+    Raises:
+        ValueError: If the entity-group file is not found in the solution.
+    """
+    with entity_lock(solution_dir, entity_group_id):
+        found = _find_local_entity_file(solution_dir, "ENTITY_GROUP", entity_group_id)
+        if found is None:
+            msg = f"Entity group {entity_group_id} not found in solution. Save the entity group first."
+            raise ValueError(msg)
+        group_file, group_data = found
+
+        existing = group_data.setdefault("memberIds", [])
+        if not isinstance(existing, list):
+            msg = f"Entity group file {group_file} has a non-list 'memberIds' field; refusing to overwrite."
+            raise ValueError(msg)
+
+        seen = {eid for eid in existing if isinstance(eid, str)}
+        added = 0
+        for eid in entity_ids:
+            if eid in seen:
+                continue
+            existing.append(eid)
+            seen.add(eid)
+            added += 1
+
+        atomic_write_text(group_file, json.dumps(group_data, indent=4) + "\n")
+        return group_file, added
+
+
+def add_group_permissions_to_local_group(
+    solution_dir: Path,
+    user_group_id: str,
+    permissions: list[dict],
+) -> tuple[Path, int]:
+    """Append GroupPermission dicts to a local USER entity-group export file's ``permissions``.
+
+    Finds the entity-group file under ``solution_dir/entity-groups/`` whose
+    ``entity.id.id`` matches *user_group_id* AND whose ``entity.type`` is
+    ``"USER"``. Each permission's ``userGroupId`` is overwritten with the
+    user-group reference derived from *user_group_id*; callers don't have to
+    repeat it. Permissions are stored on the ``EntityGroupExportData``
+    wrapper (top-level, not nested under ``entity``) per the TB import
+    schema. The list is initialized if absent.
+
+    Dedupe key is ``(roleId.id, entityGroupId.id or None)`` — the semantic
+    identity of a permission. New permissions whose key already appears in
+    the existing list (or earlier in *permissions*) are dropped so repeat
+    invocations are idempotent.
+
+    Returns ``(file_path, added_count)`` where ``added_count`` is the
+    number of permissions that were actually written (excludes duplicates).
+
+    Raises:
+        ValueError: If the entity-group file is not found in the solution,
+            its ``type`` is not ``"USER"``, or the existing ``permissions``
+            field is not a list.
+    """
+    with entity_lock(solution_dir, user_group_id):
+        found = _find_local_entity_file(solution_dir, "ENTITY_GROUP", user_group_id)
+        if found is None:
+            msg = f"Entity group {user_group_id} not found in solution. Save the entity group first."
+            raise ValueError(msg)
+        group_file, group_data = found
+
+        group_type = group_data.get("entity", {}).get("type")
+        if group_type != "USER":
+            msg = (
+                f"Entity group {user_group_id} has type {group_type!r}; "
+                "group permissions can only be attached to USER groups."
+            )
+            raise ValueError(msg)
+
+        existing = group_data.setdefault("permissions", [])
+        if not isinstance(existing, list):
+            msg = f"Entity group file {group_file} has a non-list 'permissions' field; refusing to overwrite."
+            raise ValueError(msg)
+
+        user_group_ref = {"entityType": "ENTITY_GROUP", "id": user_group_id}
+
+        def _key(perm: dict) -> tuple[str | None, str | None]:
+            role = perm.get("roleId") or {}
+            target = perm.get("entityGroupId") or {}
+            role_id = role.get("id") if isinstance(role, dict) else None
+            target_id = target.get("id") if isinstance(target, dict) else None
+            return role_id, target_id
+
+        seen: set[tuple[str | None, str | None]] = {_key(p) for p in existing if isinstance(p, dict)}
+        added = 0
+        for perm in permissions:
+            key = _key(perm)
+            if key in seen:
+                continue
+            perm["userGroupId"] = user_group_ref
+            existing.append(perm)
+            seen.add(key)
+            added += 1
+
+        atomic_write_text(group_file, json.dumps(group_data, indent=4) + "\n")
+        return group_file, added
+
+
+def find_local_entity(solution_dir: Path, entity_type: str, entity_id: str) -> dict | None:
+    """Return the entity export-data dict for *entity_id*, or None if missing.
+
+    Walks ``solution_dir/<entity-dir>/*.json`` looking for a file whose
+    ``entity.id.id`` matches. Used by ``tb emulator add`` to validate that
+    the device exists locally before persisting the task.
+    """
+    found = _find_local_entity_file(solution_dir, entity_type, entity_id)
+    return found[1] if found else None
+
+
+def merge_entity_attributes(
+    solution_dir: Path,
+    entity_type: str,
+    entity_id: str,
+    scope: str,
+    data: dict,
+) -> Path:
+    """Merge attribute key-value pairs into a local entity's ``attributes`` block.
+
+    Performs the read-modify-write under ``entity_lock`` so concurrent
+    ``tb attributes save`` calls against the same entity serialize cleanly.
+    *scope* is one of ``SERVER_SCOPE`` / ``SHARED_SCOPE`` / ``CLIENT_SCOPE``;
+    *data* is the user-supplied ``{key: value}`` mapping.
+
+    Existing attribute entries (matched by ``key``) are replaced; new keys
+    are appended. Each value is coerced into the appropriate
+    ``booleanValue`` / ``longValue`` / ``doubleValue`` / ``strValue`` /
+    ``jsonValue`` shape, mirroring the wire-format ThingsBoard accepts.
+
+    Returns the path to the updated entity file.
+
+    Raises:
+        LocalEntityNotFoundError: If no entity file is found for
+            *entity_type* / *entity_id* in *solution_dir*. The typed
+            exception lets the command layer render a consistent
+            solution-relative message whether the file was missing
+            up-front or vanished between a pre-check and the locked
+            re-check.
+    """
+    with entity_lock(solution_dir, entity_id):
+        found = _find_local_entity_file(solution_dir, entity_type, entity_id)
+        if found is None:
+            raise LocalEntityNotFoundError(entity_type, entity_id)
+        entity_file, export_data = found
+
+        attributes = export_data.setdefault("attributes", {})
+        existing = attributes.get(scope, [])
+
+        existing_by_key: dict = {a["key"]: a for a in existing if isinstance(a, dict) and "key" in a}
+        now_ms = int(time.time() * 1000)
+        for key, value in data.items():
+            attr: dict = {"key": key, "lastUpdateTs": now_ms}
+            # Order matters: ``bool`` is a subclass of ``int`` so the bool
+            # branch must come first.
+            if isinstance(value, bool):
+                attr["booleanValue"] = value
+            elif isinstance(value, int):
+                attr["longValue"] = value
+            elif isinstance(value, float):
+                attr["doubleValue"] = value
+            elif isinstance(value, str):
+                attr["strValue"] = value
+            else:
+                attr["jsonValue"] = value
+            existing_by_key[key] = attr
+        attributes[scope] = list(existing_by_key.values())
+
+        atomic_write_text(entity_file, json.dumps(export_data, indent=4) + "\n")
+        return entity_file