datex-studio-cli 0.4.20__tar.gz → 0.4.21__tar.gz

{datex_studio_cli-0.4.20 → datex_studio_cli-0.4.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datex-studio-cli
-Version: 0.4.20
+Version: 0.4.21
 Summary: CLI for Datex Studio low-code platform, designed for LLM-based AI agents
 Project-URL: Homepage, https://github.com/datex/datex-studio-cli
 Project-URL: Documentation, https://github.com/datex/datex-studio-cli

{datex_studio_cli-0.4.20 → datex_studio_cli-0.4.21}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "datex-studio-cli"
-version = "0.4.20"
+version = "0.4.21"
 description = "CLI for Datex Studio low-code platform, designed for LLM-based AI agents"
 readme = "README.md"
 license = "MIT"

{datex_studio_cli-0.4.20 → datex_studio_cli-0.4.21}/src/dxs/__init__.py

@@ -1,4 +1,4 @@
 """Datex Studio CLI - Command-line interface for Datex Studio platform."""
 
-__version__ = "0.4.20"
+__version__ = "0.4.21"
 __app_name__ = "dxs"

{datex_studio_cli-0.4.20 → datex_studio_cli-0.4.21}/src/dxs/cli.py

@@ -70,6 +70,17 @@ def _stdout_is_pipe() -> bool:
         return False
 
 
+def _stdin_is_tty() -> bool:
+    """Whether stdin is interactive — gates confirmation prompts.
+
+    A helper for the same reason as ``_stdout_is_pipe``: tests patch it.
+    """
+    try:
+        return sys.stdin.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
 def _ensure_utf8_streams() -> None:
     """Force stdout/stderr to UTF-8 so non-ASCII output never crashes the CLI.
 
@@ -571,7 +582,7 @@ def register_commands() -> None:
 @click.pass_context
 def _after_command(ctx: click.Context, result: Any, **kwargs: Any) -> Any:
     """Run post-command hooks (telemetry success event + PyPI update notice)."""
-    from dxs.utils.update_check import maybe_show_update_notice
+    from dxs.utils.update_check import maybe_show_update_notice, maybe_show_update_result
 
     dxs_ctx: DxsContext | None = ctx.find_object(DxsContext)
 
@@ -585,6 +596,13 @@ def _after_command(ctx: click.Context, result: Any, **kwargs: Any) -> Any:
     except Exception:  # noqa: BLE001
         pass
 
+    # The background-upgrade outcome is the result of an explicit user
+    # action, so it is not gated by --no-update-check.
+    try:
+        maybe_show_update_result()
+    except Exception:  # noqa: BLE001 - never let the update check break the CLI
+        pass
+
     skip = bool(dxs_ctx and dxs_ctx.no_update_check)
     try:
         maybe_show_update_notice(skip=skip)
@@ -606,13 +624,23 @@ def _ctx_extras(dxs_ctx: "DxsContext | None") -> dict[str, Any]:
 
 
 @cli.command("update")
-def update_cmd() -> None:
-    """Check PyPI for a newer release and print the upgrade command.
-
-    This command never performs the upgrade itself — run the printed
-    command in a fresh shell. This avoids the running-binary file-lock
-    issues that any in-process upgrade hits on Windows.
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
+@click.option(
+    "--check",
+    "check_only",
+    is_flag=True,
+    help="Only check for a newer release and print the upgrade command.",
+)
+def update_cmd(yes: bool, check_only: bool) -> None:
+    """Upgrade dxs to the latest release on PyPI.
+
+    On macOS/Linux this process is replaced by the installer's upgrade
+    command (uv/pipx/pip), so its output appears right here. On Windows
+    the running dxs.exe locks its own files, so the upgrade runs in a
+    detached background helper after dxs exits — the outcome is reported
+    on the next dxs run, with details in ~/.datex/update.log.
     """
+    import shutil
     import time
 
     from dxs.utils.update_check import (
@@ -620,8 +648,14 @@ def update_cmd() -> None:
         _fetch_latest_version,
         _read_cache,
         _write_cache,
+        count_windows_dxs_processes,
+        detect_upgrade_argv,
         detect_upgrade_command,
+        is_dev_install,
         is_newer,
+        is_windows,
+        perform_upgrade_posix,
+        perform_upgrade_windows,
     )
 
     click.echo(f"Current version: {__version__}", err=True)
@@ -636,11 +670,8 @@ def update_cmd() -> None:
         click.echo("You are on the latest version.", err=True)
         return
 
-    upgrade_cmd = detect_upgrade_command()
     click.echo("", err=True)
     click.echo(f"  A new release of dxs is available: {__version__} → {latest}", err=True)
-    click.echo(f"  To upgrade, run: {upgrade_cmd}", err=True)
-    click.echo(f"  https://pypi.org/project/{PACKAGE_NAME}/{latest}/", err=True)
 
     # Refresh the cache and suppress the auto-banner for the next dedupe
     # window — the user has explicitly seen the news.
@@ -651,6 +682,75 @@ def update_cmd() -> None:
     cache["last_notified_at"] = now
     _write_cache(cache)
 
+    if check_only:
+        click.echo(f"  To upgrade, run: {detect_upgrade_command()}", err=True)
+        click.echo(f"  https://pypi.org/project/{PACKAGE_NAME}/{latest}/", err=True)
+        return
+
+    if is_dev_install():
+        click.echo(
+            "This is a development install (source checkout / editable). "
+            "Upgrade it with: git pull && uv sync",
+            err=True,
+        )
+        sys.exit(1)
+
+    argv = detect_upgrade_argv()
+    resolved = shutil.which(argv[0])
+    if resolved is None:
+        click.echo(
+            f"Cannot find '{argv[0]}' on PATH — install it or upgrade manually with: "
+            f"{detect_upgrade_command()}",
+            err=True,
+        )
+        sys.exit(1)
+    argv = [resolved, *argv[1:]]
+
+    if not yes:
+        if not _stdin_is_tty():
+            click.echo(
+                "Not an interactive session — re-run with --yes to upgrade.",
+                err=True,
+            )
+            sys.exit(1)
+        click.confirm(f"  Upgrade to {latest} now?", abort=True, err=True)
+
+    if is_windows():
+        running = count_windows_dxs_processes()
+        if running is not None and running > 1:
+            click.echo(
+                f"  Warning: {running} dxs processes are running (dxs studio, another "
+                "terminal?). The upgrade may fail until they all exit.",
+                err=True,
+            )
+        try:
+            log_path = perform_upgrade_windows(argv, latest)
+        except OSError as e:
+            click.echo(f"Failed to start the background upgrade: {e}", err=True)
+            sys.exit(1)
+        click.echo("  The upgrade will run in the background once dxs exits.", err=True)
+        click.echo(f"  Log: {log_path}", err=True)
+        click.echo(
+            "  The outcome will be reported the next time you run dxs — give it a minute.",
+            err=True,
+        )
+        return
+
+    click.echo(f"  Running: {' '.join(argv)}", err=True)
+    # execvp never returns on success, so the result_callback (telemetry
+    # success event) won't run — record it here first.
+    try:
+        from dxs.core.telemetry import record_end
+
+        record_end(exit_code=0, ctx_extras={})
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        perform_upgrade_posix(argv)
+    except OSError as e:
+        click.echo(f"Upgrade failed to start: {e}", err=True)
+        sys.exit(1)
+
 
 # Register commands when module loads
 register_commands()

datex_studio_cli-0.4.21/src/dxs/utils/update_check.py

@@ -0,0 +1,452 @@
+"""PyPI update notifier + self-upgrade machinery.
+
+After each command, if the on-disk cache says a newer version exists on
+PyPI, print a one-time banner to stderr telling the user how to upgrade.
+The PyPI fetch happens in a background daemon thread, so a stale cache is
+refreshed for *next* time. The current run never blocks on the network.
+
+``dxs update`` performs the upgrade itself. The mechanics differ by
+platform because of how each OS treats files belonging to a running
+process:
+
+- POSIX (macOS/Linux): ``os.execvp`` replaces this process with the
+  upgrader (uv/pipx/pip). Replacing files out from under a dead process
+  is a non-event on POSIX, and the upgrader's output lands in the same
+  terminal.
+- Windows: the ``dxs.exe`` launcher shim holds an exclusive image lock
+  until the *whole* process tree exits (the shim spawns python and
+  waits), and loaded ``.pyd`` files are locked too — so no in-process
+  approach can work. Instead we spawn a detached ``cmd`` helper that
+  waits for both PIDs to exit (gated on image name, bounded), runs the
+  upgrade with output captured to ``~/.datex/update.log``, and a pending
+  marker lets the *next* dxs run report the outcome.
+
+Environment / flag controls:
+- ``DXS_NO_UPDATE_CHECK=1`` disables both the check and the banner.
+- ``--no-update-check`` (CLI flag) does the same per-invocation.
+- ``DXS_UPDATE_CHECK_DEBUG=1`` surfaces sender errors (development only).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+import click
+
+from dxs import __version__
+from dxs.utils.paths import datex_home_path, get_datex_home
+
+PYPI_URL = "https://pypi.org/pypi/datex-studio-cli/json"
+PACKAGE_NAME = "datex-studio-cli"
+CACHE_TTL_SECONDS = 24 * 60 * 60
+NOTIFY_DEDUPE_SECONDS = 60 * 60  # at most one banner per hour per machine
+HTTP_TIMEOUT_SECONDS = 2.0
+
+UPDATE_LOG_FILE = "update.log"
+UPDATE_HELPER_FILE = "update_helper.cmd"
+UPDATE_PENDING_FILE = "update_pending.json"
+# After this long, a pending background upgrade that hasn't landed is
+# reported as failed (with the log path) instead of silently forgotten.
+UPDATE_PENDING_STALE_SECONDS = 15 * 60
+
+_HELPER_MAX_TRIES = 300  # ~5 min of 1s polls per waited-on PID
+
+_CREATE_NO_WINDOW = 0x08000000
+_CREATE_NEW_PROCESS_GROUP = 0x00000200
+_CREATE_BREAKAWAY_FROM_JOB = 0x01000000
+
+_CI_ENV_VARS = ("CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "BUILDKITE", "TF_BUILD")
+
+
+def _cache_path() -> Path:
+    return get_datex_home() / "update_check.json"
+
+
+def _debug(msg: str) -> None:
+    if os.environ.get("DXS_UPDATE_CHECK_DEBUG", "").lower() in ("1", "true", "yes"):
+        click.echo(f"[update-check] {msg}", err=True)
+
+
+def is_disabled() -> bool:
+    """Return True if the update check has been disabled via env var."""
+    return os.environ.get("DXS_NO_UPDATE_CHECK", "").lower() in ("1", "true", "yes")
+
+
+def _is_ci() -> bool:
+    return any(os.environ.get(v) for v in _CI_ENV_VARS)
+
+
+def _read_cache() -> dict[str, Any] | None:
+    path = _cache_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+        if isinstance(data, dict):
+            return data
+    except (json.JSONDecodeError, OSError) as e:
+        _debug(f"cache read failed: {e}")
+    return None
+
+
+def _write_cache(data: dict[str, Any]) -> None:
+    try:
+        _cache_path().write_text(json.dumps(data))
+    except OSError as e:
+        _debug(f"cache write failed: {e}")
+
+
+def _fetch_latest_version() -> str | None:
+    """Fetch the latest version from PyPI. Returns None on any failure."""
+    try:
+        import httpx
+
+        response = httpx.get(PYPI_URL, timeout=HTTP_TIMEOUT_SECONDS)
+        response.raise_for_status()
+        latest = response.json()["info"]["version"]
+        return str(latest) if latest else None
+    except Exception as e:  # noqa: BLE001 - never let telemetry break the CLI
+        _debug(f"fetch failed: {e}")
+        return None
+
+
+def _refresh_cache_worker() -> None:
+    latest = _fetch_latest_version()
+    if not latest:
+        return
+    cache = _read_cache() or {}
+    cache["latest"] = latest
+    cache["checked_at"] = time.time()
+    _write_cache(cache)
+
+
+def _maybe_refresh_async(cache: dict[str, Any] | None) -> None:
+    """Spawn a daemon thread to refresh the cache if it's missing or stale."""
+    needs_refresh = (
+        cache is None or (time.time() - float(cache.get("checked_at", 0))) > CACHE_TTL_SECONDS
+    )
+    if not needs_refresh:
+        return
+    thread = threading.Thread(target=_refresh_cache_worker, daemon=True, name="dxs-update-check")
+    thread.start()
+
+
+_VERSION_RE = re.compile(r"^(\d+)(?:\.(\d+))?(?:\.(\d+))?")
+
+
+def _parse_version(v: str) -> tuple[int, int, int]:
+    """Parse an X.Y.Z version into a tuple. Pre-release suffixes are ignored.
+
+    Returns (0, 0, 0) on unparseable input — treated as oldest possible.
+    """
+    m = _VERSION_RE.match(v.strip())
+    if not m:
+        return (0, 0, 0)
+    return (int(m.group(1) or 0), int(m.group(2) or 0), int(m.group(3) or 0))
+
+
+def is_newer(candidate: str, current: str) -> bool:
+    """Return True if `candidate` is a newer version than `current`."""
+    return _parse_version(candidate) > _parse_version(current)
+
+
+def detect_upgrade_argv() -> list[str]:
+    """Best-effort detection of how dxs was installed, as an argv list."""
+    exe = sys.executable
+    # uv tool installs land under ~/.local/share/uv/tools/<pkg>/...
+    if "/uv/tools/" in exe or "\\uv\\tools\\" in exe:
+        return ["uv", "tool", "upgrade", PACKAGE_NAME]
+    # pipx installs land under ~/.local/pipx/venvs/<pkg>/...
+    if "/pipx/" in exe or "\\pipx\\" in exe:
+        return ["pipx", "upgrade", PACKAGE_NAME]
+    # Fallback: pip in whatever interpreter the user is on
+    return [exe, "-m", "pip", "install", "--upgrade", PACKAGE_NAME]
+
+
+def detect_upgrade_command() -> str:
+    """The upgrade command as a display string (for banners and --check)."""
+    return " ".join(detect_upgrade_argv())
+
+
+def is_windows() -> bool:
+    """Seam for the platform split — patchable in tests on any host."""
+    return sys.platform == "win32"
+
+
+def is_dev_install() -> bool:
+    """True when dxs runs from a source checkout or local/editable install.
+
+    Such installs must not be upgraded from PyPI — ``git pull && uv sync``
+    is the correct path. Detection reads the distribution's
+    ``direct_url.json``: present only for local-path installs (PyPI installs
+    don't have one). No distribution record at all also counts as dev.
+    """
+    try:
+        from importlib.metadata import distribution
+
+        dist = distribution(PACKAGE_NAME)
+    except Exception:  # noqa: BLE001 - not installed as a distribution
+        return True
+    try:
+        text = dist.read_text("direct_url.json")
+    except Exception:  # noqa: BLE001
+        return False
+    if not text:
+        return False
+    try:
+        info = json.loads(text)
+    except json.JSONDecodeError:
+        return False
+    dir_info = info.get("dir_info")
+    if isinstance(dir_info, dict) and dir_info.get("editable"):
+        return True
+    url = info.get("url", "")
+    return isinstance(url, str) and url.startswith("file://")
+
+
+def perform_upgrade_posix(argv: list[str]) -> None:
+    """Replace this process with the upgrader. Does not return on success.
+
+    The exec frees every file handle before uv/pipx/pip starts rewriting
+    the venv, and the upgrader inherits the terminal for its output.
+    Raises OSError if the exec itself fails to start.
+    """
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os.execvp(argv[0], argv)  # noqa: S606 - deliberate process replacement
+
+
+def _windows_helper_script(argv: list[str], pid: int, ppid: int, log_path: Path) -> str:
+    """Generate the detached cmd helper that performs a Windows upgrade.
+
+    The helper waits for two PIDs: this python process and its parent —
+    the ``dxs.exe`` trampoline that holds the image-file lock. Each wait is
+    gated on the image name (``python``/``dxs``) so a PID that belongs to
+    something else — dxs launched from a shell, or a recycled PID — is
+    never awaited, and bounded so a wedged process can't pin the helper
+    forever (the upgrade then runs anyway and the log records the real
+    error). ``ping -n 2`` is the sleep: ``timeout`` requires an
+    interactive console and fails in a detached process.
+    """
+    cmdline = subprocess.list2cmdline(argv)
+    log = str(log_path)
+    lines = [
+        "@echo off",
+        "setlocal",
+        "set TRIES=0",
+        f'echo [dxs update] waiting for dxs (pids {pid}, {ppid}) to exit... > "{log}"',
+        ":wait_self",
+        "set /a TRIES+=1",
+        f"if %TRIES% GTR {_HELPER_MAX_TRIES} goto run",
+        f'tasklist /FI "PID eq {pid}" /FO CSV /NH 2>nul | findstr /i "python" >nul',
+        "if not errorlevel 1 (",
+        "ping -n 2 127.0.0.1 >nul",
+        "goto wait_self",
+        ")",
+        ":wait_parent",
+        "set /a TRIES+=1",
+        f"if %TRIES% GTR {_HELPER_MAX_TRIES} goto run",
+        f'tasklist /FI "PID eq {ppid}" /FO CSV /NH 2>nul | findstr /i "dxs" >nul',
+        "if not errorlevel 1 (",
+        "ping -n 2 127.0.0.1 >nul",
+        "goto wait_parent",
+        ")",
+        ":run",
+        f'echo [dxs update] running: {cmdline} >> "{log}"',
+        f'{cmdline} >> "{log}" 2>&1',
+        f'echo [dxs update] upgrader exit code: %errorlevel% >> "{log}"',
+        "endlocal",
+        "",
+    ]
+    return "\r\n".join(lines)
+
+
+def _spawn_detached_helper(helper_path: Path) -> None:
+    """Launch the helper fully detached so it survives this process's exit.
+
+    CREATE_BREAKAWAY_FROM_JOB is attempted first in case the launcher put
+    us in a kill-on-close job object; if the job refuses breakaway the
+    spawn is retried without it. CREATE_NO_WINDOW keeps the helper's
+    console invisible.
+    """
+    argv = ["cmd.exe", "/d", "/c", str(helper_path)]
+    common: dict[str, Any] = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "close_fds": True,
+        "cwd": str(helper_path.parent),
+    }
+    flags = _CREATE_NO_WINDOW | _CREATE_NEW_PROCESS_GROUP
+    try:
+        subprocess.Popen(argv, creationflags=flags | _CREATE_BREAKAWAY_FROM_JOB, **common)
+    except OSError:
+        subprocess.Popen(argv, creationflags=flags, **common)
+
+
+def perform_upgrade_windows(argv: list[str], latest: str) -> Path:
+    """Write the helper + pending marker and spawn the detached upgrade.
+
+    Returns the log path the helper will write to. Raises OSError if the
+    helper cannot be written or spawned (the marker is cleared so the
+    next run doesn't report a phantom failure).
+    """
+    home = get_datex_home()
+    log_path = home / UPDATE_LOG_FILE
+    helper_path = home / UPDATE_HELPER_FILE
+    script = _windows_helper_script(argv, pid=os.getpid(), ppid=os.getppid(), log_path=log_path)
+    helper_path.write_text(script, newline="")
+    _write_pending(
+        {
+            "from_version": __version__,
+            "to_version": latest,
+            "log": str(log_path),
+            "started_at": time.time(),
+        }
+    )
+    try:
+        _spawn_detached_helper(helper_path)
+    except OSError:
+        _clear_pending()
+        raise
+    return log_path
+
+
+def count_windows_dxs_processes() -> int | None:
+    """Count running ``dxs.exe`` launchers (Windows only). None if unknown.
+
+    More than one means another dxs (``dxs studio``, another terminal) holds
+    venv locks that will fail the background upgrade until it exits.
+    """
+    try:
+        out = subprocess.run(
+            ["tasklist", "/FI", "IMAGENAME eq dxs.exe", "/FO", "CSV", "/NH"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        ).stdout
+        return sum(1 for line in out.splitlines() if line.lower().startswith('"dxs.exe"'))
+    except Exception:  # noqa: BLE001 - preflight is best-effort
+        return None
+
+
+def _pending_path() -> Path:
+    # Read on every invocation via the post-command hook — must not mkdir,
+    # or `dxs reset` would see ~/.datex/ resurrected immediately.
+    return datex_home_path() / UPDATE_PENDING_FILE
+
+
+def _write_pending(data: dict[str, Any]) -> None:
+    (get_datex_home() / UPDATE_PENDING_FILE).write_text(json.dumps(data))
+
+
+def _clear_pending() -> None:
+    try:
+        _pending_path().unlink()
+    except OSError:
+        pass
+
+
+def maybe_show_update_result() -> None:
+    """One-shot outcome notice for a background (Windows) upgrade.
+
+    The detached helper can't print to the original console, so the marker
+    written at spawn time is judged here on the next run: current version
+    reached the target → success; still on the old version past the stale
+    window → failure, pointing at the log. In between, stay quiet and keep
+    the marker.
+    """
+    path = _pending_path()
+    if not path.exists():
+        return
+    try:
+        data = json.loads(path.read_text())
+        to_version = data["to_version"]
+        started_at = float(data.get("started_at", 0))
+        log = data.get("log", "")
+        if not isinstance(to_version, str):
+            raise TypeError("to_version must be a string")
+    except Exception:  # noqa: BLE001 - corrupt marker: clear and move on
+        _clear_pending()
+        return
+
+    if not is_newer(to_version, __version__):
+        click.echo(f"dxs upgrade complete — now running {__version__}.", err=True)
+        _clear_pending()
+    elif time.time() - started_at > UPDATE_PENDING_STALE_SECONDS:
+        click.echo(
+            f"A background upgrade to dxs {to_version} was started but you are "
+            f"still on {__version__} — it appears to have failed.",
+            err=True,
+        )
+        if log:
+            click.echo(f"See the log: {log}", err=True)
+        _clear_pending()
+
+
+def _stderr_is_tty() -> bool:
+    """True when stderr is attached to a TTY.
+
+    Only stderr matters — the banner is written there. Piping stdout (e.g.
+    ``dxs odata ... | jq``) leaves stderr untouched, so the user still sees
+    the banner in their terminal. Redirecting stderr (``2>log``) suppresses
+    it, as intended.
+    """
+    return sys.stderr.isatty()
+
+
+def _print_banner(latest: str, upgrade_cmd: str) -> None:
+    """Print the update banner to stderr."""
+    click.echo("", err=True)
+    click.echo(
+        f"  A new release of dxs is available: {__version__} → {latest}",
+        err=True,
+    )
+    click.echo(f"  To upgrade, run: {upgrade_cmd}", err=True)
+    click.echo(f"  https://pypi.org/project/{PACKAGE_NAME}/{latest}/", err=True)
+
+
+def maybe_show_update_notice(skip: bool = False) -> None:
+    """If the cache shows a newer version, print a one-time banner to stderr.
+
+    Always returns quickly — the PyPI fetch happens in a background thread
+    that only writes to the cache. The first run on a stale cache prints
+    nothing; the next run sees the refreshed cache and prints the banner.
+    Dedupe keeps it to one banner per ``NOTIFY_DEDUPE_SECONDS`` window so
+    fast-fire commands don't spam.
+
+    Args:
+        skip: If True, skip both the check and any cache refresh. Used to
+            honor ``--no-update-check``.
+    """
+    if skip or is_disabled() or _is_ci():
+        return
+    if not _stderr_is_tty():
+        return
+
+    cache = _read_cache()
+    _maybe_refresh_async(cache)
+
+    if not cache:
+        return
+
+    latest = cache.get("latest")
+    if not isinstance(latest, str) or not is_newer(latest, __version__):
+        return
+
+    last_notified = float(cache.get("last_notified_at", 0))
+    if time.time() - last_notified < NOTIFY_DEDUPE_SECONDS:
+        return
+
+    _print_banner(latest, detect_upgrade_command())
+
+    cache["last_notified_at"] = time.time()
+    _write_cache(cache)