keboola-cli 0.63.4__py3-none-any.whl

keboola_agent_cli/errors.py

@@ -0,0 +1,248 @@
+"""Error types and helpers for Keboola Agent CLI."""
+
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    """Stable machine-readable error codes emitted by kbagent.
+
+    ``str`` mixin means values compare equal to their plain-string equivalents
+    and serialise as plain strings in JSON output -- no wire-format change.
+
+    Versioning: adding a new code = minor bump; renaming / removing = major bump.
+    """
+
+    # Auth / access
+    INVALID_TOKEN = "INVALID_TOKEN"
+    ACCESS_DENIED = "ACCESS_DENIED"
+    PERMISSION_DENIED = "PERMISSION_DENIED"
+    MISSING_MASTER_TOKEN = "MISSING_MASTER_TOKEN"
+    UNAUTHORIZED = "UNAUTHORIZED"  # Bearer-auth rejection by `kbagent serve` (0.40.0+)
+
+    # Network / transport
+    TIMEOUT = "TIMEOUT"
+    CONNECTION_ERROR = "CONNECTION_ERROR"
+    RETRY_EXHAUSTED = "RETRY_EXHAUSTED"
+
+    # API / generic
+    API_ERROR = "API_ERROR"
+    NOT_FOUND = "NOT_FOUND"
+    ALREADY_EXISTS = "ALREADY_EXISTS"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    INVALID_ARGUMENT = "INVALID_ARGUMENT"
+    INVALID_FORMAT = "INVALID_FORMAT"
+    USAGE_ERROR = "USAGE_ERROR"
+    MISSING_PARAMETER = "MISSING_PARAMETER"
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+    # `kbagent serve` HTTP envelope (0.40.0+)
+    HTTP_ERROR = "HTTP_ERROR"  # Generic HTTP-layer error (Starlette HTTPException passthrough)
+    INTERNAL_ERROR = "INTERNAL_ERROR"  # Uncaught exception inside a route handler
+
+    # Configuration
+    CONFIG_ERROR = "CONFIG_ERROR"
+    NOT_INITIALIZED = "NOT_INITIALIZED"
+    INIT_ERROR = "INIT_ERROR"
+
+    # Jobs
+    QUEUE_JOB_FAILED = "QUEUE_JOB_FAILED"
+    QUEUE_JOB_TIMEOUT = "QUEUE_JOB_TIMEOUT"
+    STORAGE_JOB_FAILED = "STORAGE_JOB_FAILED"
+    STORAGE_JOB_TIMEOUT = "STORAGE_JOB_TIMEOUT"
+    QUERY_JOB_FAILED = "QUERY_JOB_FAILED"
+    QUERY_JOB_TIMEOUT = "QUERY_JOB_TIMEOUT"
+
+    # Variables
+    NO_VARIABLE_ROWS = "NO_VARIABLE_ROWS"
+    MALFORMED_VARIABLES_ROW = "MALFORMED_VARIABLES_ROW"
+
+    # Storage
+    UPLOAD_FAILED = "UPLOAD_FAILED"
+    EXPORT_EMPTY_MANIFEST = "EXPORT_EMPTY_MANIFEST"
+    EXPORT_NO_FILE = "EXPORT_NO_FILE"
+    EXPORT_NO_URL = "EXPORT_NO_URL"
+    NOT_SLICED = "NOT_SLICED"
+    FILE_NO_URL = "FILE_NO_URL"
+
+    # I/O
+    FILE_NOT_FOUND = "FILE_NOT_FOUND"
+    DIR_NOT_FOUND = "DIR_NOT_FOUND"
+    READ_ERROR = "READ_ERROR"
+    WRITE_ERROR = "WRITE_ERROR"
+    INPUT_ERROR = "INPUT_ERROR"
+
+    # Lineage
+    NODE_NOT_FOUND = "NODE_NOT_FOUND"
+
+    # Sharing
+    INVALID_SHARING_TYPE = "INVALID_SHARING_TYPE"
+    NOT_LINKED_BUCKET = "NOT_LINKED_BUCKET"
+
+    # KAI (AI Service)
+    KAI_ERROR = "KAI_ERROR"
+    KAI_NOT_ENABLED = "KAI_NOT_ENABLED"
+
+    # Workspace / Query
+    MISSING_QUERY = "MISSING_QUERY"
+    WORKSPACE_NOT_FOUND = "WORKSPACE_NOT_FOUND"
+
+    # Sync
+    PARENT_CONFIG_NOT_TRACKED = "PARENT_CONFIG_NOT_TRACKED"
+    VARIABLE_LINK_UNRESOLVED = "VARIABLE_LINK_UNRESOLVED"
+    SYNC_CONFLICT = "SYNC_CONFLICT"
+
+    # Encryption
+    ENCRYPTION_FAILED = "ENCRYPTION_FAILED"
+
+    # Job / queue (extensions from 0.22.0)
+    JOB_TIMEOUT_TERMINATED = "JOB_TIMEOUT_TERMINATED"
+
+    # Flow (new in 0.22.0)
+    SCHEDULE_DELETE_FAILED = "SCHEDULE_DELETE_FAILED"
+    # Conditional-flow validation (replaces INVALID_FLOW_DAG; since 0.57.0)
+    INVALID_FLOW_DEFINITION = "INVALID_FLOW_DEFINITION"
+
+    # Data apps (new in 0.27.0)
+    DATA_APP_BUILD_FAILED = "DATA_APP_BUILD_FAILED"
+    DATA_APP_DEPLOY_TIMEOUT = "DATA_APP_DEPLOY_TIMEOUT"
+    DATA_APP_INVALID_GIT = "DATA_APP_INVALID_GIT"
+
+    # Data apps - secrets + validate-repo (new in 0.28.0)
+    DATA_APP_INVALID_SECRET = "DATA_APP_INVALID_SECRET"
+    DATA_APP_INVALID_REPO = "DATA_APP_INVALID_REPO"
+    DATA_APP_REPO_VALIDATION_BLOCKING = "DATA_APP_REPO_VALIDATION_BLOCKING"
+
+    # Developer Portal (since 0.48.0)
+    DP_LOGIN_FAILED = "DP_LOGIN_FAILED"
+    DP_MFA_REQUIRED = "DP_MFA_REQUIRED"
+    DP_APP_NOT_FOUND = "DP_APP_NOT_FOUND"
+    DP_PUBLISH_REQUIREMENTS_MISSING = "DP_PUBLISH_REQUIREMENTS_MISSING"
+    DP_ICON_UPLOAD_FAILED = "DP_ICON_UPLOAD_FAILED"
+
+
+def mask_token(token: str) -> str:
+    """Mask a Keboola Storage API token for safe display.
+
+    Preserves the prefix (part before the first dash) and the last 4 characters,
+    replacing the middle with '...'.
+
+    Examples:
+        mask_token("901-55555-fakeTestTokenDoNotUseXXXXXXXX")
+        -> "901-...XXXX"
+
+        mask_token("abc") -> "***"
+        mask_token("") -> "***"
+    """
+    if len(token) < 8:
+        return "***"
+
+    dash_index = token.find("-")
+    if dash_index == -1 or dash_index >= len(token) - 4:
+        return "***"
+
+    prefix = token[:dash_index]
+    last4 = token[-4:]
+    return f"{prefix}-...{last4}"
+
+
+class KeboolaApiError(Exception):
+    """Raised when a Keboola API call fails.
+
+    Optional ``details`` payload lets the service layer attach structured
+    context (e.g. a fetched log tail, the remote-cancelled job dict) that
+    the command layer surfaces in ``--json`` mode without changing the
+    stable top-level error envelope. Keep keys small and side-effect-free;
+    PR9 will lock this schema down with a versioned enum.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 0,
+        error_code: str | ErrorCode = ErrorCode.UNKNOWN_ERROR,
+        retryable: bool = False,
+        details: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.retryable = retryable
+        self.details: dict = details if details is not None else {}
+
+
+class ConfigError(Exception):
+    """Raised when there is a configuration problem."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class SyncConflictError(Exception):
+    """Raised when ``sync pull --force`` would overwrite locally-modified
+    configs whose remote **also** changed since the last pull -- a true 3-way
+    merge conflict (local and remote both diverged from the synced base).
+
+    ``--force`` deliberately bypasses the "preserve locally-modified files"
+    guard, so without this check it would silently adopt the edited on-disk
+    file as the new synced baseline (issue: force-pull baseline corruption).
+    Rather than discard un-pushed work, the pull aborts *before writing
+    anything* and asks the user to resolve each conflict (push or discard
+    local edits, then pull again).
+
+    ``conflicts`` carries one dict per conflicting config/row so the command
+    layer can list them. Each dict has ``component_id``, ``config_id``,
+    ``config_name``, ``path``, ``scope`` (``"config"`` or ``"row"``), and an
+    optional ``row_id``.
+    """
+
+    def __init__(self, conflicts: list[dict[str, str]]) -> None:
+        self.conflicts = conflicts
+        n = len(conflicts)
+        plural = "s" if n != 1 else ""
+        message = (
+            f"{n} config{plural} ha{'ve' if n != 1 else 's'} un-pushed local "
+            f"edits AND changed on the remote since the last pull (merge "
+            f"conflict). `sync pull --force` refuses to overwrite them so your "
+            f"local work is not lost. Resolve each conflict first: review with "
+            f"`kbagent sync diff`, then either `kbagent sync push` your local "
+            f"edits or discard them, and pull again."
+        )
+        super().__init__(message)
+        self.message = message
+        self.error_code = ErrorCode.SYNC_CONFLICT
+
+
+class PermissionDeniedError(Exception):
+    """Raised when an operation is blocked by the permission policy."""
+
+    def __init__(self, operation: str, message: str = "") -> None:
+        if not message:
+            message = f"Operation '{operation}' is blocked by the active permission policy."
+        super().__init__(message)
+        self.operation = operation
+        self.message = message
+
+
+_ERROR_CODE_TO_TYPE: dict[str, str] = {
+    ErrorCode.INVALID_TOKEN: "authentication",
+    ErrorCode.MISSING_MASTER_TOKEN: "authentication",
+    ErrorCode.TIMEOUT: "network",
+    ErrorCode.CONNECTION_ERROR: "network",
+    ErrorCode.RETRY_EXHAUSTED: "network",
+    ErrorCode.NOT_FOUND: "not_found",
+    ErrorCode.CONFIG_ERROR: "configuration",
+    ErrorCode.VALIDATION_ERROR: "validation",
+    ErrorCode.SYNC_CONFLICT: "conflict",
+    ErrorCode.PERMISSION_DENIED: "authorization",
+    ErrorCode.DP_LOGIN_FAILED: "authentication",
+    ErrorCode.DP_MFA_REQUIRED: "authentication",
+    ErrorCode.DP_APP_NOT_FOUND: "not_found",
+    ErrorCode.DP_PUBLISH_REQUIREMENTS_MISSING: "validation",
+    ErrorCode.DP_ICON_UPLOAD_FAILED: "api",
+}
+
+
+def map_error_code_to_type(error_code: str) -> str:
+    """Map a machine-readable error code to a broad error type category."""
+    return _ERROR_CODE_TO_TYPE.get(error_code, "api")

keboola_agent_cli/http_base.py

@@ -0,0 +1,315 @@
+"""Base HTTP client with shared retry, timeout, and error handling logic.
+
+Both KeboolaClient (Storage API) and ManageClient (Manage API) inherit
+from BaseHttpClient to avoid duplicating the retry loop, error mapping,
+and message sanitization code.
+"""
+
+import json
+import logging
+import os
+import platform
+import time
+from typing import Any, Self
+from urllib.parse import urlparse, urlunparse
+
+import httpx
+
+from .constants import (
+    APP_NAME,
+    BACKOFF_BASE,
+    ENV_CONVERSATION_ID,
+    MAX_API_ERROR_LENGTH,
+    MAX_RETRIES,
+    MAX_RETRY_AFTER_SECONDS,
+    RETRYABLE_STATUS_CODES,
+)
+from .errors import ErrorCode, KeboolaApiError, mask_token
+
+logger = logging.getLogger(__name__)
+
+
+def build_user_agent() -> str:
+    """Build the User-Agent that signs every Keboola API call.
+
+    Format (RFC 7231 product + comment):
+
+        keboola-cli/<version> (<os> <release>; <arch>; <impl> <pyver>)
+        e.g. keboola-cli/0.45.0 (Darwin 25.3.0; arm64; CPython 3.12.7)
+
+    Keboola's edge logs this verbatim (DataDog access logs), so the fleet can
+    be segmented by version and OS/arch. Only neutral host metadata is sent --
+    never ``platform.node()`` (the hostname is PII). Identity ("which project /
+    user") is resolved server-side from the token, never derived client-side.
+    """
+    from . import __version__
+
+    return (
+        f"{APP_NAME}/{__version__} "
+        f"({platform.system()} {platform.release()}; "
+        f"{platform.machine()}; "
+        f"{platform.python_implementation()} {platform.python_version()})"
+    )
+
+
+class BaseHttpClient:
+    """Shared HTTP client with retry, timeout, and error handling.
+
+    Provides:
+    - _do_request(method, path, **kwargs): HTTP request with retry + backoff
+    - _raise_api_error(response, base_url=None): error mapping with truncation
+    - Context manager support (close, __enter__, __exit__)
+
+    Subclasses must call super().__init__() with base_url, token, headers,
+    and optional timeout.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        headers: dict[str, str],
+        timeout: httpx.Timeout | None = None,
+    ) -> None:
+        from .constants import DEFAULT_TIMEOUT
+
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._masked_token = mask_token(token)
+        # Sign every request centrally so all subclasses share one UA string
+        # (and OS/version enrichment) instead of hardcoding it five times.
+        headers["User-Agent"] = build_user_agent()
+        conversation_id = os.environ.get(ENV_CONVERSATION_ID, "")
+        if conversation_id:
+            headers["X-Conversation-ID"] = conversation_id
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout or DEFAULT_TIMEOUT,
+            headers=headers,
+        )
+
+    @staticmethod
+    def _derive_service_url(stack_url: str, service_prefix: str) -> str:
+        """Derive a service base URL by replacing 'connection.' in the hostname.
+
+        E.g. _derive_service_url("https://connection.keboola.com", "queue")
+             -> "https://queue.keboola.com"
+        """
+        parsed = urlparse(stack_url)
+        hostname = parsed.hostname or ""
+        new_host = hostname.replace("connection.", f"{service_prefix}.", 1)
+        if new_host == hostname:
+            logger.warning(
+                "%s URL derivation did not change hostname: %s",
+                service_prefix,
+                hostname,
+            )
+        return urlunparse(parsed._replace(netloc=new_host))
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _do_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        client: httpx.Client | None = None,
+        base_url: str | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Execute an HTTP request with retry and exponential backoff.
+
+        Retries on status codes 429, 500, 502, 503, 504 up to MAX_RETRIES times
+        with exponential backoff (1s, 2s, 4s).
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            path: URL path relative to base_url.
+            client: Optional httpx.Client to use (defaults to self._client).
+                Useful for subclasses that maintain multiple clients (e.g. queue client).
+            base_url: Optional base URL for error messages (defaults to self._base_url).
+            **kwargs: Additional arguments passed to httpx.Client.request().
+
+        Returns:
+            The HTTP response on success.
+
+        Raises:
+            KeboolaApiError: On HTTP errors (with masked token) or after retries exhausted.
+        """
+        http_client = client or self._client
+        url_label = base_url or self._base_url
+        last_response: httpx.Response | None = None
+
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = http_client.request(method, path, **kwargs)
+
+                if response.status_code < 400:
+                    return response
+
+                if response.status_code in RETRYABLE_STATUS_CODES and attempt < MAX_RETRIES - 1:
+                    if response.status_code == 429:
+                        retry_after = response.headers.get("Retry-After")
+                        if retry_after:
+                            try:
+                                delay = min(float(retry_after), MAX_RETRY_AFTER_SECONDS)
+                            except ValueError:
+                                delay = BACKOFF_BASE * (2**attempt)
+                        else:
+                            delay = BACKOFF_BASE * (2**attempt)
+                    else:
+                        delay = BACKOFF_BASE * (2**attempt)
+                    logger.debug(
+                        "Retry attempt %d/%d for %s %s (status %d), delay %.1fs",
+                        attempt + 1,
+                        MAX_RETRIES,
+                        method,
+                        path,
+                        response.status_code,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    last_response = response
+                    continue
+
+                self._raise_api_error(response, url_label)
+
+            except httpx.TimeoutException as exc:
+                if attempt < MAX_RETRIES - 1:
+                    delay = BACKOFF_BASE * (2**attempt)
+                    logger.debug(
+                        "Retry attempt %d/%d for %s %s (timeout), delay %.1fs",
+                        attempt + 1,
+                        MAX_RETRIES,
+                        method,
+                        path,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    continue
+                raise KeboolaApiError(
+                    message=f"Request timed out connecting to {url_label} (token: {self._masked_token})",
+                    status_code=0,
+                    error_code=ErrorCode.TIMEOUT,
+                    retryable=True,
+                ) from exc
+
+            except httpx.ConnectError as exc:
+                if attempt < MAX_RETRIES - 1:
+                    delay = BACKOFF_BASE * (2**attempt)
+                    logger.debug(
+                        "Retry attempt %d/%d for %s %s (connection error), delay %.1fs",
+                        attempt + 1,
+                        MAX_RETRIES,
+                        method,
+                        path,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    continue
+                raise KeboolaApiError(
+                    message=f"Cannot connect to {url_label} (token: {self._masked_token})",
+                    status_code=0,
+                    error_code=ErrorCode.CONNECTION_ERROR,
+                    retryable=True,
+                ) from exc
+
+        if last_response is not None:
+            self._raise_api_error(last_response, url_label)
+
+        raise KeboolaApiError(
+            message=f"Request failed after {MAX_RETRIES} retries to {url_label} (token: {self._masked_token})",
+            status_code=0,
+            error_code=ErrorCode.RETRY_EXHAUSTED,
+            retryable=True,
+        )
+
+    def _raise_api_error(self, response: httpx.Response, base_url: str | None = None) -> None:
+        """Convert an HTTP error response into a KeboolaApiError.
+
+        Parses the response body for error messages, truncates long messages
+        to MAX_API_ERROR_LENGTH characters, and maps status codes to
+        appropriate error codes.
+
+        Args:
+            response: The HTTP error response.
+            base_url: Optional URL label for error messages.
+
+        Raises:
+            KeboolaApiError: Always raised with appropriate error code and message.
+        """
+        status = response.status_code
+        url_label = base_url or self._base_url
+
+        try:
+            body = response.json()
+            # Real Keboola APIs answer with one of these keys in priority
+            # order. Two caveats:
+            #   1. Keboola Metastore puts the HTTP status code into `error`
+            #      as an int (e.g. {"error": 422}) -- using `or` would
+            #      shadow the actual error message in `errors`/`exception`.
+            #      So we only accept `error` if it's a non-empty string.
+            #   2. `errors`/`detail` are lists of dicts (FastAPI / metastore
+            #      422 shape); we json.dumps them so the f-string render
+            #      below doesn't print `[{...}]` repr.
+            err_field = body.get("error")
+            api_message = (
+                err_field
+                if isinstance(err_field, str) and err_field
+                else (
+                    body.get("exception")
+                    or body.get("message")
+                    or body.get("description")
+                    or body.get("detail")
+                    or body.get("errors")
+                    or json.dumps(body)
+                )
+            )
+            if not isinstance(api_message, str):
+                api_message = json.dumps(api_message)
+        except Exception:
+            api_message = response.text
+
+        # Truncate to prevent Rich markup injection and excessive output
+        if isinstance(api_message, str) and len(api_message) > MAX_API_ERROR_LENGTH:
+            api_message = api_message[:MAX_API_ERROR_LENGTH] + "..."
+
+        if status == 401:
+            raise KeboolaApiError(
+                message=f"Invalid or expired token (token: {self._masked_token}): {api_message}",
+                status_code=status,
+                error_code=ErrorCode.INVALID_TOKEN,
+                retryable=False,
+            )
+
+        if status == 403:
+            raise KeboolaApiError(
+                message=f"Access denied (token: {self._masked_token}): {api_message}",
+                status_code=status,
+                error_code=ErrorCode.ACCESS_DENIED,
+                retryable=False,
+            )
+
+        if status == 404:
+            raise KeboolaApiError(
+                message=f"Resource not found: {api_message}",
+                status_code=status,
+                error_code=ErrorCode.NOT_FOUND,
+                retryable=False,
+            )
+
+        retryable = status in RETRYABLE_STATUS_CODES
+        raise KeboolaApiError(
+            message=f"API error {status} from {url_label} (token: {self._masked_token}): {api_message}",
+            status_code=status,
+            error_code=ErrorCode.API_ERROR,
+            retryable=retryable,
+        )

keboola_agent_cli/json_utils.py

@@ -0,0 +1,126 @@
+"""JSON deep-merge and nested-path utilities.
+
+Used by ``config update`` to patch configuration content without
+losing sibling keys -- the exact problem that MCP server's
+``update_config`` tool has (keboola/mcp-server#468).
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+def deep_merge(target: dict[str, Any], source: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *source* into *target* (non-mutating).
+
+    Rules:
+    * dict + dict → recursively merged
+    * anything else → *source* wins (including list replaces list)
+
+    Returns a new dict; neither *target* nor *source* is mutated.
+    """
+    result = copy.deepcopy(target)
+    for key, src_value in source.items():
+        if key in result and isinstance(result[key], dict) and isinstance(src_value, dict):
+            result[key] = deep_merge(result[key], src_value)
+        else:
+            result[key] = copy.deepcopy(src_value)
+    return result
+
+
+def get_nested_value(obj: Any, path: str) -> Any:
+    """Retrieve a value from a nested structure using a dot-separated path.
+
+    Supports integer segments for list indexing (e.g. ``"tables.0.name"``).
+
+    Raises ``KeyError`` or ``IndexError`` if the path does not exist.
+    """
+    for segment in path.split("."):
+        if isinstance(obj, dict):
+            obj = obj[segment]
+        elif isinstance(obj, list):
+            obj = obj[int(segment)]
+        else:
+            raise KeyError(f"Cannot traverse into {type(obj).__name__} with key '{segment}'")
+    return obj
+
+
+def set_nested_value(obj: dict[str, Any], path: str, value: Any) -> dict[str, Any]:
+    """Set a value at a dot-separated path, creating intermediate dicts.
+
+    Returns a deep-copied dict with the value set — *obj* is not mutated.
+
+    Supports integer segments for list indexing on **existing** lists
+    (new intermediate containers are always dicts).
+    """
+    result = copy.deepcopy(obj)
+    segments = path.split(".")
+    current: Any = result
+    for segment in segments[:-1]:
+        if isinstance(current, dict):
+            if segment not in current:
+                current[segment] = {}
+            current = current[segment]
+        elif isinstance(current, list):
+            current = current[int(segment)]
+        else:
+            raise KeyError(f"Cannot traverse into {type(current).__name__} with key '{segment}'")
+
+    last = segments[-1]
+    if isinstance(current, dict):
+        current[last] = copy.deepcopy(value)
+    elif isinstance(current, list):
+        current[int(last)] = copy.deepcopy(value)
+    else:
+        raise KeyError(f"Cannot set key '{last}' on {type(current).__name__}")
+    return result
+
+
+def compute_diff(
+    old: dict[str, Any],
+    new: dict[str, Any],
+    path: str = "",
+) -> list[str]:
+    """Produce a human-readable list of changes between two dicts.
+
+    Each entry looks like:
+        ``"parameters.tables.count: 5 -> 10"``
+        ``"parameters.newKey: (absent) -> 'hello'"``
+        ``"parameters.removed: 42 -> (absent)"``
+    """
+    changes: list[str] = []
+    all_keys = sorted(set(list(old.keys()) + list(new.keys())))
+
+    for key in all_keys:
+        full_path = f"{path}.{key}" if path else key
+        in_old = key in old
+        in_new = key in new
+
+        if in_old and in_new:
+            old_val = old[key]
+            new_val = new[key]
+            if isinstance(old_val, dict) and isinstance(new_val, dict):
+                changes.extend(compute_diff(old_val, new_val, full_path))
+            elif old_val != new_val:
+                changes.append(f"{full_path}: {_fmt(old_val)} -> {_fmt(new_val)}")
+        elif in_old and not in_new:
+            changes.append(f"{full_path}: {_fmt(old[key])} -> (absent)")
+        else:
+            changes.append(f"{full_path}: (absent) -> {_fmt(new[key])}")
+
+    return changes
+
+
+def _fmt(value: Any) -> str:
+    """Format a value for diff display — truncate long representations."""
+    if isinstance(value, str):
+        s = repr(value)
+    elif isinstance(value, dict):
+        s = f"{{...}} ({len(value)} keys)"
+    elif isinstance(value, list):
+        s = f"[...] ({len(value)} items)"
+    else:
+        s = repr(value)
+    max_len = 80
+    return s if len(s) <= max_len else s[: max_len - 3] + "..."