snowflake-cli 3.25.0__tar.gz → 3.26.0__tar.gz

{snowflake_cli-3.25.0 → snowflake_cli-3.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: snowflake-cli
-Version: 3.25.0
+Version: 3.26.0
 Summary: Snowflake CLI
 Project-URL: Source code, https://github.com/snowflakedb/snowflake-cli
 Project-URL: Bug Tracker, https://github.com/snowflakedb/snowflake-cli/issues

{snowflake_cli-3.25.0 → snowflake_cli-3.26.0}/RELEASE-NOTES.md

@@ -23,13 +23,31 @@
 ## Fixes and improvements
 
 
+# v3.26.0
+
+## Deprecations
+
+## New additions
+* `snow connection test --enable-diag` now appends [SnowCD](https://docs.snowflake.com/en/user-guide/snowcd)-style per-endpoint connectivity checks (health, latency, certificate info, and an effective network policy summary) to the existing `SnowflakeConnectionTestReport.txt`. Stdout is unchanged. Pass `--print-diag` with `--enable-diag` to print that same report to stdout. Replaces the end-of-life SnowCD tool.
+* `app.yml` (version 2) for Snowflake App Runtime projects is now generally available, and no longer needs a feature flag. `snow app setup` creates an `app.yml` for new projects. Existing `snowflake.yml` projects keep working as before.
+* Git metadata support for `snow dbt deploy` is now available. `--git-commit` and `--git-branch` record the source commit and branch in the project's `last_deployed_from` metadata. These values will also be auto-detected from GitHub Actions environments if no explicit flags are specified.
+
+## Fixes and improvements
+* `snow app deploy` for Snowflake App Runtime projects now explains a failure while preparing code storage in terms of the statement that actually failed. A missing database or schema is reported as such instead of as a missing privilege, a privilege error names only the grant that statement needs, and a rejected stage encryption type is named explicitly.
+* `snow app deploy` for Snowflake App Runtime projects no longer surfaces a raw connector traceback when uploading code fails. The error now names the stage or workspace being written to, how many files had already uploaded, and what to do next. Failed file transfers, which were previously not caught at all, are reported the same way.
+* `snow helpers detect-encoding` now detects when the Windows console isn't configured for UTF-8 output (independent of the CLI's own encoding settings) and points the user at the fix — `chcp.com 65001` for cmd.exe/Git Bash, or the docs for PowerShell 5.x. The CLI's startup encoding warning surfaces the same note, but only when it isn't already warning about a Python encoding mismatch — run `snow helpers detect-encoding` for the full picture.
+* `snow app deploy` for Snowflake App Runtime projects no longer needs OWNERSHIP on the code stage and CREATE STAGE on the schema to redeploy. The upload used to start by dropping the stage and creating it again, so a role holding only WRITE could deploy once and then never again — and a role allowed to drop the stage but not create one lost the stage entirely. The stage is now only dropped when the deploying role can also recreate it; otherwise its contents are cleared, with a warning that files deleted from the project since the last deploy may survive on the stage.
+* Snowflake App Runtime projects now use temporary code storage by default. `snow app setup` leaves `code_stage`/`code_workspace` out of `app.yml`, and `snow app deploy` provisions a temporary `<app>_CODE` stage (or a `<app>_CODE` workspace for personal databases, which don't support stages) just for the build and drops it once the build finishes. Because the name is derived from the app, `--build-only` can still find and drop what `--upload-only` created. Set `code_stage` or `code_workspace` in `app.yml` to keep a persisted stage/workspace instead.
+* Fixed `snow helpers check-version` failing with "Could not determine the latest Snowflake CLI version" when the local version cache file was corrupted. A corrupted or unreadable cache now falls back to a live network fetch instead of silently returning nothing.
+* The passive new-version banner no longer blocks CLI startup. The version cache is refreshed in a background thread while the command runs, and the banner is shown after the command completes (including on `--help`, `--version`, and `--info`).
+
 # v3.25.0
 
 ## Deprecations
 
 ## New additions
 * `snow connection add` now supports `--client-store-temporary-credential`, which writes `client_store_temporary_credential = true` to the new connection in `config.toml`.
-* `snow sql --local-only` default can now be set via the `SNOWFLAKE_CLI_SQL_LOCAL_ONLY` environment variable. Accepted values: `1/true/yes/on` (enable) and `0/false/no/off` (disable). When unset, the default remains `false`.
+* `snow sql --local-only` default can now be set via the `SNOWFLAKE_CLI_SQL_LOCAL_ONLY` environment variable. When unset, the default remains `false`.
 * `snow app events` now accepts `--instance <N>` (Snowflake App Runtime only) to retrieve live container logs from a specific service instance. Useful when horizontal scaling is active and more than one instance is running. Defaults to instance 0 when the flag is omitted.
 * The `snow app` commands now support an `app.yml` (version 2) for Snowflake App Runtime projects; when present it drives the flow instead of `snowflake.yml` (the Native App flow is unchanged). Its `targets` block declares named per-environment deployments, and a new `--target` flag on `deploy`, `open`, `events`, `teardown`, and `validate` selects which one to use. `snow app deploy` runs an upload → build → deploy pipeline that can be limited to a single phase with `--upload-only`, `--build-only`, or `--promote-only`.
 * `dbt_projects_profiles.yml` support in `snow dbt deploy` is now generally available. When the profiles directory contains a `dbt_projects_profiles.yml`, it takes precedence over `profiles.yml` and is staged into the deployed project under its own name. The profiles directory is the one given by `--profiles-dir`, or the project root when that option is omitted, so projects that already contain a `dbt_projects_profiles.yml` alongside `profiles.yml` will now deploy with the former and emit a warning.
@@ -37,6 +55,8 @@
 ## Fixes and improvements
 * A `snow app` command no longer fails because it could not clean up after itself. If a leftover file cannot be deleted — common on Windows, where an editor or antivirus can be holding it — the command still succeeds and warns which directory was left behind. When the bundle directory cannot be cleared before bundling, the command now stops with an explanation of what to do instead of a permissions error.
 * `snow app` commands no longer delete anything in a Snowflake App Runtime project's `output` directory apart from the bundle they created there. A project that keeps its own build results, exports or notebook output under `output` lost them to a command that only meant to bundle.
+* `snow app deploy` for Snowflake App Runtime projects now retries a file upload that fails while transferring to cloud storage, instead of failing the whole deploy on the first network blip. Errors the server returned about the statement itself, such as a missing stage or a missing privilege, are not retried.
+* `snow app deploy` with workspace-backed storage no longer fails with an "object already exists" error when the workspace already has a live version. That is the normal state on every deploy after the first, and only one of the two error codes the server can return for it was being tolerated.
 * `snow app events` for Snowflake App Runtime projects can now return more events by requesting a higher `--last` value.
 * `snow app deploy` with workspace-backed storage now builds from `versions/live/` (the current working state) instead of the last committed version. In the Workspaces editor, files auto-save to the live version continuously — reading `versions/last` during the build phase caused stale content to be deployed when running from a live workspace session.
 * DCM projects: the `snow dcm preview`, `snow dcm refresh`, and `snow dcm test`
@@ -47,6 +67,7 @@
 * `snow dcm deploy`, `snow dcm plan` and `snow dcm purge` no longer require an active warehouse. Progress tracking read the result with `RESULT_SCAN`, which requires a warehouse.
 * `snow dcm deploy`, `snow dcm plan` and `snow dcm purge` now wrap a change line too wide for the terminal, with its continuation aligned under the change instead of breaking back to the left margin. The file list shown while uploading uses the same tree guides as the changeset.
 * `snow streamlit deploy --replace`: fixed a crash when replacing a legacy `ROOT_LOCATION` Streamlit app with a versioned deployment.
+* `snow snowpark deploy` now sends only the packages an entity declares for its artifact repository in the object's `PACKAGES` clause. Packages that `snow snowpark build` resolved from the Anaconda channel were merged into the same clause, so a project using `artifact_repository` alongside a `requirements.txt` could fail to deploy with the same package requested at two versions, or ask the artifact repository for a package that only exists in Anaconda. The command now warns when it leaves those packages out. An entity using an artifact repository therefore has to declare every package it needs — `snowflake-snowpark-python` included — under its `artifact_repository_packages` or `packages`; a project that deployed only because the Anaconda-resolved packages were merged into the clause will fail until they are declared in `snowflake.yml`.
 * Upgraded `GitPython` from 3.1.57 to 3.1.58.
 * Upgraded the Python interpreter embedded in Linux binaries from 3.10.16 to 3.10.21.
 * Upgraded pip from 26.1.2 to 26.2.1.

{snowflake_cli-3.25.0 → snowflake_cli-3.26.0}/src/snowflake/cli/__about__.py

@@ -19,7 +19,7 @@ import re
 import subprocess
 from enum import Enum, unique
 
-VERSION = "3.25.0"
+VERSION = "3.26.0"
 
 
 def get_display_version() -> str:

{snowflake_cli-3.25.0 → snowflake_cli-3.26.0}/src/snowflake/cli/_app/cli_app.py

@@ -36,11 +36,7 @@ from snowflake.cli._app.dev.pycharm_remote_debug import (
 )
 from snowflake.cli._app.main_typer import SnowCliMainTyper
 from snowflake.cli._app.printing import MessageResult, print_result
-from snowflake.cli._app.version_check import (
-    get_new_version_msg,
-    reset_new_version_banner_suppression,
-    show_new_version_banner_callback,
-)
+from snowflake.cli._app.version_check import show_new_version_banner_callback
 from snowflake.cli.api.config import (
     config_init,
     get_config_manager,
@@ -184,13 +180,10 @@ class CliAppFactory:
             return self._app
 
         app = SnowCliMainTyper()
-        reset_new_version_banner_suppression()
-        new_version_msg = get_new_version_msg()
 
         @app.callback(
             invoke_without_command=True,
-            epilog=new_version_msg,
-            result_callback=show_new_version_banner_callback(new_version_msg),
+            result_callback=show_new_version_banner_callback,
             add_help_option=False,  # custom_help option added below
             help=f"Snowflake CLI tool for developers [v{__about__.VERSION}]",
         )

snowflake_cli-3.26.0/src/snowflake/cli/_app/main_typer.py

@@ -0,0 +1,118 @@
+# Copyright (c) 2024 Snowflake Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+from snowflake.cli._app.version_check import (
+    maybe_show_new_version_banner,
+    reset_banner_display_state,
+    start_background_refresh,
+)
+from snowflake.cli.api.cli_global_context import get_cli_context
+from snowflake.cli.api.commands.flags import DEFAULT_CONTEXT_SETTINGS, DebugOption
+from snowflake.cli.api.config import config_init
+from snowflake.cli.api.console import cli_console
+
+
+def _handle_exception(exception: Exception):
+    if get_cli_context().enable_tracebacks:
+        raise exception
+    else:
+        cli_console.warning(
+            "\nAn unexpected exception occurred. Use --debug option to see the traceback. Exception message:\n\n"
+            + exception.__str__()
+        )
+        raise SystemExit(1)
+
+
+def _config_file_argv(*call_args) -> list[str]:
+    """Argv for an early ``--config-file`` peek before Click/Typer parsing."""
+    if call_args:
+        argv: list[str] = []
+        for arg in call_args:
+            if isinstance(arg, (list, tuple)):
+                argv.extend(str(item) for item in arg)
+            else:
+                argv.append(str(arg))
+        return argv
+    return sys.argv[1:]
+
+
+def _maybe_init_config_from_args(*call_args) -> None:
+    """Apply ``--config-file`` before version-cache work when argv is available."""
+    argv = _config_file_argv(*call_args)
+    for index, arg in enumerate(argv):
+        if arg == "--config-file" and index + 1 < len(argv):
+            config_path = Path(argv[index + 1])
+            break
+        if arg.startswith("--config-file="):
+            config_path = Path(arg.split("=", 1)[1])
+            break
+    else:
+        return
+
+    # Do not create a missing config file here; Click's ``exists=True`` option
+    # validates the path and reports a clear error.
+    if config_path.exists():
+        config_init(config_path)
+
+
+def _run_cli_invocation(self, run):
+    """Shared startup/teardown for both ``__call__`` and ``main`` entry points."""
+    DebugOption.callback(any(param in sys.argv for param in DebugOption.param_decls))
+    reset_banner_display_state()
+    try:
+        return run()
+    except Exception as exception:
+        _handle_exception(exception)
+    finally:
+        maybe_show_new_version_banner()
+
+
+class SnowCliMainTyper(typer.Typer):
+    """
+    Top-level SnowCLI Typer.
+    It contains global exception handling.
+    """
+
+    def __init__(self):
+        super().__init__(
+            context_settings=DEFAULT_CONTEXT_SETTINGS,
+            pretty_exceptions_show_locals=False,
+            add_completion=True,
+        )
+
+    def __call__(self, *args, **kwargs):
+        def run():
+            _maybe_init_config_from_args(*args)
+            start_background_refresh()
+            return super(SnowCliMainTyper, self).__call__(*args, **kwargs)
+
+        return _run_cli_invocation(self, run)
+
+    def main(self, args=None, prog_name=None, **extra):
+        cli_args = list(args or ())
+
+        def run():
+            _maybe_init_config_from_args(*cli_args)
+            start_background_refresh()
+            return super(SnowCliMainTyper, self).main(
+                args=cli_args, prog_name=prog_name, **extra
+            )
+
+        return _run_cli_invocation(self, run)

{snowflake_cli-3.25.0 → snowflake_cli-3.26.0}/src/snowflake/cli/_app/telemetry.py

@@ -67,6 +67,7 @@ class CLITelemetryField(Enum):
     # _get_auth_type.
     COMMAND_AUTH_TYPE = "command_auth_type"
     COMMAND_AGENT_ENVIRONMENT = "command_agent_environment"
+    COMMAND_AGENT_SESSION_ID = "command_agent_session_id"
     # Configuration
     CONFIG_FEATURE_FLAGS = "config_feature_flags"
     CONFIG_PROVIDER_TYPE = "config_provider_type"
@@ -395,6 +396,16 @@ def _detect_agent_environment() -> str:
     return "UNKNOWN"
 
 
+def _get_agent_session_id() -> str:
+    """Return the detected agent's session ID, or empty string."""
+    agent = _detect_agent_environment()
+    if agent == "CORTEX":
+        return os.environ.get("CORTEX_SESSION_ID", "").strip()
+    if agent == "CLAUDE_CODE":
+        return os.environ.get("CLAUDE_CODE_SESSION_ID", "").strip()
+    return ""
+
+
 def command_info() -> str:
     info = _find_command_info()
     command = ".".join(info[CLITelemetryField.COMMAND])
@@ -471,6 +482,7 @@ class CLITelemetryClient:
             CLITelemetryField.COMMAND_CI_AUTH_TYPE: _get_ci_auth_type(),
             CLITelemetryField.COMMAND_AUTH_TYPE: _get_auth_type(),
             CLITelemetryField.COMMAND_AGENT_ENVIRONMENT: _detect_agent_environment(),
+            CLITelemetryField.COMMAND_AGENT_SESSION_ID: _get_agent_session_id(),
             CLITelemetryField.CONFIG_FEATURE_FLAGS: {
                 k: str(v) for k, v in get_feature_flags_section().items()
             },

snowflake_cli-3.26.0/src/snowflake/cli/_app/version_check.py

@@ -0,0 +1,400 @@
+import json
+import logging
+import os
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+
+import requests
+from packaging.version import Version
+from snowflake.cli.__about__ import VERSION
+from snowflake.cli.api.cli_global_context import get_cli_context
+from snowflake.cli.api.config import (
+    CLI_SECTION,
+    IGNORE_NEW_VERSION_WARNING_KEY,
+    get_config_bool_value,
+    get_config_manager,
+    get_file_io_encoding,
+)
+from snowflake.cli.api.console import cli_console
+from snowflake.cli.api.sanitizers import sanitize_for_terminal
+from snowflake.cli.api.secure_path import SecurePath
+
+log = logging.getLogger(__name__)
+
+REPOSITORY_URL_PIP = "https://pypi.org/pypi/snowflake-cli/json"
+REPOSITORY_URL_BREW = "https://formulae.brew.sh/api/formula/snowflake-cli.json"
+
+# Set by an explicit version-reporting command (e.g. `snow helpers check-version`)
+# so the passive upgrade banner does not duplicate the command's own output.
+_suppress_new_version_banner = False
+_banner_shown = False
+
+# How often to refresh the version cache (seconds)
+VERSION_CACHE_REFRESH_INTERVAL = 60 * 60  # 1 hour
+# How often to show the new version message (seconds)
+NEW_VERSION_MESSAGE_INTERVAL = 60 * 60 * 24 * 7  # 1 week
+# Per-request timeout when querying PyPI/Homebrew (seconds)
+VERSION_FETCH_TIMEOUT = 1
+# Max wait for an in-flight background refresh before showing the passive banner
+VERSION_REFRESH_JOIN_TIMEOUT = 2 * VERSION_FETCH_TIMEOUT + 0.5
+
+_refresh_lock = threading.Lock()
+_refresh_thread: threading.Thread | None = None
+
+
+def should_ignore_new_version_warning() -> bool:
+    return get_config_bool_value(
+        CLI_SECTION, key=IGNORE_NEW_VERSION_WARNING_KEY, default=False
+    )
+
+
+def was_warning_shown_recently(last_time_shown: float | int | None) -> bool:
+    """
+    Returns True if the new version warning was shown recently (within the interval),
+    meaning we should NOT show the warning again yet.
+    """
+    if not last_time_shown:
+        return False
+    now = time.time()
+    return last_time_shown >= now - NEW_VERSION_MESSAGE_INTERVAL
+
+
+def start_background_refresh() -> None:
+    """Start a daemon thread to refresh the version cache if needed."""
+    if should_ignore_new_version_warning():
+        return
+    _VersionCache().schedule_background_refresh()
+
+
+def wait_for_refresh(timeout: float = VERSION_REFRESH_JOIN_TIMEOUT) -> None:
+    """Block until the background refresh thread finishes or times out."""
+    thread = _refresh_thread
+    if thread is not None and thread.is_alive():
+        thread.join(timeout=timeout)
+
+
+def reset_background_refresh_thread() -> None:
+    """Wait for and clear any in-flight background refresh thread."""
+    global _refresh_thread
+    wait_for_refresh()
+    _refresh_thread = None
+
+
+def get_new_version_msg() -> str | None:
+    try:
+        if should_ignore_new_version_warning():
+            return None
+        wait_for_refresh()
+        cache = _VersionCache()
+        last_version = cache.get_cached_version()
+        last_time_shown = cache.get_last_time_shown()
+        current_version = Version(VERSION)
+        if (
+            last_version
+            and last_version > current_version
+            and not was_warning_shown_recently(last_time_shown)
+        ):
+            cache.update_last_time_shown()
+            newest = sanitize_for_terminal(str(last_version))
+            current = sanitize_for_terminal(VERSION)
+            return (
+                f"New version of Snowflake CLI available. "
+                f"Newest: {newest}, current: {current}"
+            )
+        return None
+    except Exception:
+        log.debug("Failed to determine new version message", exc_info=True)
+        return None
+
+
+@dataclass
+class CliVersionInfo:
+    current_version: str
+    latest_version: str | None
+    update_available: bool
+
+
+def get_version_info(*, force_refresh: bool = False) -> CliVersionInfo:
+    """Resolve the current and latest available Snowflake CLI versions.
+
+    Unlike the passive upgrade banner, this always reports the result: it
+    ignores the ``ignore_new_version_warning`` config and the "shown recently"
+    throttle so an explicit check is never silenced. ``force_refresh`` bypasses
+    the on-disk cache and queries the package repositories directly.
+    """
+    latest_version = _VersionCache().get_last_version(force_refresh=force_refresh)
+    update_available = bool(latest_version and latest_version > Version(VERSION))
+    return CliVersionInfo(
+        current_version=VERSION,
+        latest_version=str(latest_version) if latest_version else None,
+        update_available=update_available,
+    )
+
+
+def reset_banner_display_state() -> None:
+    """Reset per-invocation banner state before running a command."""
+    global _banner_shown, _suppress_new_version_banner
+    _banner_shown = False
+    _suppress_new_version_banner = False
+
+
+def reset_new_version_banner_suppression() -> None:
+    """Reset banner suppression; alias kept for callers outside ``__call__``."""
+    reset_banner_display_state()
+
+
+def suppress_new_version_banner() -> None:
+    """Mute the passive upgrade banner for the current invocation.
+
+    Used by commands that already report version status themselves so the
+    banner does not duplicate their output.
+    """
+    global _suppress_new_version_banner
+    _suppress_new_version_banner = True
+
+
+def record_version_check_displayed() -> None:
+    """Record that the user saw an explicit version check.
+
+    Uses the same throttle timestamp as the passive upgrade banner so a
+    successful ``snow helpers check-version`` does not immediately re-prompt
+    on the next command.
+    """
+    try:
+        _VersionCache().update_last_time_shown()
+    except Exception:
+        log.debug("Failed to record version check display time", exc_info=True)
+
+
+def maybe_show_new_version_banner() -> None:
+    """Show the passive upgrade banner if an update is available."""
+    global _banner_shown
+    if _banner_shown or _suppress_new_version_banner or get_cli_context().silent:
+        return
+    msg = get_new_version_msg()
+    if msg:
+        _banner_shown = True
+        cli_console.stderr_warning(msg)
+
+
+def show_new_version_banner_callback(*args, **kwargs):
+    """Result callback for the root command; shows the banner after execution."""
+    maybe_show_new_version_banner()
+
+
+class _VersionCache:
+    _last_time = "last_time_check"
+    _version = "version"
+    _last_time_shown = "last_time_shown"
+    _last_attempt = "last_attempt"
+
+    @property
+    def _version_cache_file(self):
+        """Get version cache file path with lazy evaluation."""
+        return SecurePath(get_config_manager().file_path.parent / ".cli_version.cache")
+
+    def __init__(self):
+        self._cache_file = self._version_cache_file
+
+    def _atomic_write(self, content: str) -> None:
+        """Write content to the cache file atomically via a temp-file + rename."""
+        encoding = get_file_io_encoding()
+        dest = self._cache_file.path
+        SecurePath(dest).parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = None
+        try:
+            fd, tmp_path = tempfile.mkstemp(dir=dest.parent, suffix=".tmp")
+            with os.fdopen(fd, "w", encoding=encoding) as f:
+                f.write(content)
+            os.replace(tmp_path, dest)
+            tmp_path = None
+        except OSError:
+            if tmp_path is not None:
+                try:
+                    os.unlink(tmp_path)
+                except OSError:
+                    pass
+            log.debug(
+                "Atomic cache write failed, falling back to direct write",
+                exc_info=True,
+            )
+            try:
+                self._cache_file.write_text(content)
+            except OSError:
+                log.debug("Direct cache write also failed", exc_info=True)
+
+    def _read_cache_data(self) -> dict | None:
+        if not self._cache_file.exists():
+            return None
+        try:
+            parsed = json.loads(self._cache_file.read_text(file_size_limit_mb=1))
+            if not isinstance(parsed, dict):
+                log.debug(
+                    "Version cache has unexpected JSON type: %s",
+                    type(parsed).__name__,
+                )
+                return None
+            return parsed
+        except Exception:
+            log.debug("Failed to read version cache", exc_info=True)
+            return None
+
+    def schedule_background_refresh(self) -> None:
+        cache_data = self._read_cache_data()
+        if self._is_fresh(cache_data) or not self._refresh_is_overdue(cache_data):
+            return
+
+        def _run() -> None:
+            try:
+                self._mark_attempt()
+                self._update_latest_version()
+            except Exception:
+                log.debug("Background version refresh failed", exc_info=True)
+
+        global _refresh_thread
+        with _refresh_lock:
+            if _refresh_thread is not None and _refresh_thread.is_alive():
+                return
+            _refresh_thread = threading.Thread(
+                target=_run,
+                name="version-cache-refresh",
+                daemon=True,
+            )
+            _refresh_thread.start()
+
+    def _is_fresh(self, data: dict | None) -> bool:
+        if not data:
+            return False
+        try:
+            return (
+                data[_VersionCache._last_time]
+                > time.time() - VERSION_CACHE_REFRESH_INTERVAL
+            )
+        except (KeyError, TypeError):
+            return False
+
+    def _refresh_is_overdue(self, data: dict | None) -> bool:
+        if data is None:
+            return True
+        last_attempt = data.get(_VersionCache._last_attempt, 0)
+        return time.time() - last_attempt >= VERSION_CACHE_REFRESH_INTERVAL
+
+    def _mark_attempt(self) -> None:
+        try:
+            data = self._read_cache_data() or {}
+            data[_VersionCache._last_attempt] = time.time()
+            self._atomic_write(json.dumps(data))
+        except Exception:
+            log.debug("Failed to write refresh attempt timestamp", exc_info=True)
+
+    def _save_latest_version(self, version: str):
+        data = {
+            _VersionCache._last_time: time.time(),
+            _VersionCache._version: str(version),
+        }
+        old_data = self._read_cache_data()
+        if old_data:
+            if _VersionCache._last_time_shown in old_data:
+                data[_VersionCache._last_time_shown] = old_data[
+                    _VersionCache._last_time_shown
+                ]
+            if _VersionCache._last_attempt in old_data:
+                data[_VersionCache._last_attempt] = old_data[
+                    _VersionCache._last_attempt
+                ]
+        self._atomic_write(json.dumps(data))
+
+    def update_last_time_shown(self):
+        data = self._read_cache_data() or {}
+        data[_VersionCache._last_time_shown] = time.time()
+        self._atomic_write(json.dumps(data))
+
+    @staticmethod
+    def _get_version_from_pypi() -> str | None:
+        headers = {"Content-Type": "application/vnd.pypi.simple.v1+json"}
+        response = requests.get(
+            REPOSITORY_URL_PIP,
+            headers=headers,
+            timeout=VERSION_FETCH_TIMEOUT,
+        )
+        response.raise_for_status()
+        return response.json().get("info", {}).get("version", None)
+
+    @staticmethod
+    def _get_version_from_brew() -> str | None:
+        response = requests.get(
+            REPOSITORY_URL_BREW,
+            timeout=VERSION_FETCH_TIMEOUT,
+        )
+        response.raise_for_status()
+        return response.json().get("versions", {}).get("stable", None)
+
+    def _update_latest_version(self) -> Version | None:
+        # Use brew version, fallback to pypi if brew is not available.
+        # Brew repo takes longer to propagate the upgrade and is triggered later in our release process,
+        # we treat it as "slowest point" and determinant that the released version is available.
+        version = self._get_version_from_brew() or self._get_version_from_pypi()
+        if version is None:
+            return None
+        self._save_latest_version(version)
+        return Version(version)
+
+    def _read_fresh_cached_version(self) -> Version | None:
+        data = self._read_cache_data()
+        if not data:
+            return None
+        try:
+            if (
+                data[_VersionCache._last_time]
+                > time.time() - VERSION_CACHE_REFRESH_INTERVAL
+            ):
+                return Version(data[_VersionCache._version])
+        except (KeyError, TypeError, ValueError):
+            log.debug(
+                "Version cache is unreadable, refreshing from network",
+                exc_info=True,
+            )
+        return None
+
+    def _read_latest_version(self, force_refresh: bool = False) -> Version | None:
+        if not force_refresh:
+            cached = self._read_fresh_cached_version()
+            if cached is not None:
+                return cached
+        return self._update_latest_version()
+
+    def get_cached_version(self) -> Version | None:
+        """Return the cached version without touching the network."""
+        data = self._read_cache_data()
+        if not data:
+            return None
+        try:
+            return Version(data[_VersionCache._version])
+        except (KeyError, TypeError, ValueError):
+            return None
+
+    def get_last_version(self, force_refresh: bool = False) -> Version | None:
+        try:
+            if force_refresh:
+                return self._update_latest_version()
+            cache_data = self._read_cache_data()
+            if not self._is_fresh(cache_data):
+                wait_for_refresh()
+                cached = self._read_fresh_cached_version()
+                if cached is not None:
+                    return cached
+            return self._read_latest_version(force_refresh=False)
+        except Exception:  # anything, this is not a crucial feature
+            # Swallowed so a version check never breaks a command, but logged
+            # so --debug/--verbose can reveal the real cause (network error,
+            # HTTP 5xx, malformed JSON, ...) instead of only a generic message.
+            log.debug("Failed to determine the latest CLI version", exc_info=True)
+            return None
+
+    def get_last_time_shown(self) -> float | int | None:
+        data = self._read_cache_data()
+        if data is None:
+            return None
+        return data.get(_VersionCache._last_time_shown, 0)