fix: add automatic update checks (#19)

Author: LichKing-2234

README.md

@@ -30,6 +30,10 @@ You can also download a tarball from the GitHub Release page and run `atlassian/
 
 ## Update
 
+On interactive commands, the CLI checks for a newer GitHub Release at most once every 24 hours and prints an update notice to stderr when a newer release exists. It never installs updates automatically, and JSON/YAML command output is not modified.
+
+Set `ATLASSIAN_DISABLE_UPDATE_CHECK=1` to disable the automatic check.
+
 Check for a newer GitHub Release:
 
 ```bash

src/atlassian_cli/cli.py

@@ -1,8 +1,10 @@
 import os
+import sys
 from pathlib import Path
 
 import typer
 
+from atlassian_cli import __version__
 from atlassian_cli.auth.headers import parse_cli_headers
 from atlassian_cli.auth.models import AuthMode
 from atlassian_cli.commands.init import init_command
@@ -19,7 +21,7 @@
 from atlassian_cli.config.template import ensure_default_config
 from atlassian_cli.core.context import LazyExecutionContext
 from atlassian_cli.core.errors import ConfigError
-from atlassian_cli.output.modes import OutputMode
+from atlassian_cli.output.modes import OutputMode, is_machine_output
 from atlassian_cli.products.bitbucket.commands.branch import app as bitbucket_branch_app
 from atlassian_cli.products.bitbucket.commands.commit import app as bitbucket_commit_app
 from atlassian_cli.products.bitbucket.commands.pr import app as bitbucket_pr_app
@@ -34,6 +36,7 @@
 from atlassian_cli.products.jira.commands.issue import app as jira_issue_app
 from atlassian_cli.products.jira.commands.project import app as jira_project_app
 from atlassian_cli.products.jira.commands.user import app as jira_user_app
+from atlassian_cli.update import check_for_update_notice
 
 app = typer.Typer(help="Atlassian Server/Data Center CLI")
 
@@ -64,6 +67,7 @@
 
 DEFAULT_CONFIG_FILE = Path("~/.config/atlassian-cli/config.toml").expanduser()
 PRODUCT_COMMANDS = {product.value for product in Product}
+AUTO_UPDATE_CHECK_EXCLUDED_COMMANDS = {"update"}
 
 
 def _missing_product_message(config_file: Path, product: Product, *, created: bool) -> str:
@@ -72,6 +76,25 @@ def _missing_product_message(config_file: Path, product: Product, *, created: bo
     return f"Fill in [{product.value}] in {config_file} or pass --url."
 
 
+def _stderr_is_interactive() -> bool:
+    return sys.stderr.isatty()
+
+
+def _maybe_notify_update(ctx: typer.Context, *, output: OutputMode) -> None:
+    if ctx.invoked_subcommand is None or ctx.resilient_parsing:
+        return
+    if ctx.invoked_subcommand in AUTO_UPDATE_CHECK_EXCLUDED_COMMANDS:
+        return
+    if is_machine_output(output) or not _stderr_is_interactive():
+        return
+    try:
+        notice = check_for_update_notice(__version__)
+        if notice:
+            typer.echo(notice, err=True)
+    except Exception:
+        return
+
+
 @app.callback()
 def root_callback(
     ctx: typer.Context,
@@ -87,6 +110,7 @@ def root_callback(
 ) -> None:
     if ctx.invoked_subcommand is None:
         return
+    _maybe_notify_update(ctx, output=output)
     if ctx.invoked_subcommand not in PRODUCT_COMMANDS:
         return
 

src/atlassian_cli/update.py

@@ -5,6 +5,7 @@
 import subprocess
 import sys
 import tempfile
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -20,6 +21,9 @@
     f"https://raw.githubusercontent.com/{REPO_OWNER}/{REPO_NAME}/{{tag}}/install.sh"
 )
 REQUEST_TIMEOUT_SECONDS = 10
+AUTO_UPDATE_CHECK_TIMEOUT_SECONDS = 2
+AUTO_UPDATE_CHECK_INTERVAL_SECONDS = 24 * 60 * 60
+AUTO_UPDATE_CHECK_DISABLE_ENV = "ATLASSIAN_DISABLE_UPDATE_CHECK"
 
 
 class UpdateError(RuntimeError):
@@ -155,6 +159,126 @@ def get_update_info(current_version: str) -> UpdateInfo:
     )
 
 
+def auto_update_check_state_path(
+    *,
+    environ: dict[str, str] | None = None,
+    home: Path | None = None,
+) -> Path:
+    env = os.environ if environ is None else environ
+    cache_home = env.get("XDG_CACHE_HOME")
+    base_dir = Path(cache_home).expanduser() if cache_home else (home or Path.home()) / ".cache"
+    return base_dir / "atlassian-cli" / "update-check.json"
+
+
+def _env_flag_enabled(value: str | None) -> bool:
+    return value is not None and value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _read_update_check_state(state_path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(state_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _write_update_check_state(state_path: Path, state: dict[str, Any]) -> None:
+    try:
+        state_path.parent.mkdir(parents=True, exist_ok=True)
+        state_path.write_text(json.dumps(state, sort_keys=True), encoding="utf-8")
+    except OSError:
+        return
+
+
+def _record_update_check_error(
+    state_path: Path | None,
+    *,
+    checked_at: int,
+    error: Exception,
+    extra_state: dict[str, Any] | None = None,
+) -> None:
+    if state_path is None:
+        return
+    state = {
+        "last_checked_at": checked_at,
+        "last_error": str(error),
+    }
+    if extra_state:
+        state.update(extra_state)
+    _write_update_check_state(state_path, state)
+
+
+def _recently_checked(
+    state: dict[str, Any],
+    *,
+    now: int,
+    interval_seconds: int,
+) -> bool:
+    if "last_checked_at" not in state:
+        return False
+    try:
+        last_checked_at = int(state["last_checked_at"])
+    except (TypeError, ValueError):
+        return False
+    if now < last_checked_at:
+        return False
+    return now - last_checked_at < interval_seconds
+
+
+def format_update_notice(current_version: str, latest: ReleaseInfo) -> str:
+    lines = [
+        f"atlassian-cli {current_version} can be updated to {latest.tag}.",
+        "Run: atlassian update install",
+    ]
+    if latest.url:
+        lines.append(f"Release: {latest.url}")
+    return "\n".join(lines)
+
+
+def check_for_update_notice(
+    current_version: str,
+    *,
+    state_path: Path | None = None,
+    now: int | None = None,
+    environ: dict[str, str] | None = None,
+    timeout: int = AUTO_UPDATE_CHECK_TIMEOUT_SECONDS,
+    interval_seconds: int = AUTO_UPDATE_CHECK_INTERVAL_SECONDS,
+) -> str | None:
+    env = os.environ if environ is None else environ
+    if _env_flag_enabled(env.get(AUTO_UPDATE_CHECK_DISABLE_ENV)):
+        return None
+
+    checked_at = int(time.time() if now is None else now)
+    path: Path | None = None
+    release_state: dict[str, Any] | None = None
+    try:
+        path = state_path or auto_update_check_state_path(environ=env)
+        previous_state = _read_update_check_state(path)
+        if _recently_checked(previous_state, now=checked_at, interval_seconds=interval_seconds):
+            return None
+
+        latest = fetch_latest_release(timeout=timeout)
+        release_state = {
+            "last_checked_at": checked_at,
+            "latest_tag": latest.tag,
+            "latest_version": latest.version,
+            "release_url": latest.url,
+        }
+        _write_update_check_state(path, release_state)
+        update_available = is_newer_version(latest.version, current_version)
+    except Exception as exc:
+        _record_update_check_error(
+            path,
+            checked_at=checked_at,
+            error=exc,
+            extra_state=release_state,
+        )
+        return None
+    if not update_available:
+        return None
+    return format_update_notice(current_version, latest)
+
+
 def default_install_dir(
     *,
     environ: dict[str, str] | None = None,