forgexa-cli 1.20.5__tar.gz → 1.21.0__tar.gz

{forgexa_cli-1.20.5 → forgexa_cli-1.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgexa-cli
-Version: 1.20.5
+Version: 1.21.0
 Summary: Forgexa CLI — command-line client and AI agent runtime for the Forgexa platform
 Author-email: Jason Sun <dev.winds@gmail.com>
 License-Expression: MIT
@@ -113,6 +113,7 @@ forgexa board --project <project-id>
 | `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
+| `forgexa version --status` | Show auto-upgrade status (mode, active/last success/last failure) |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
 | `forgexa upgrade --target-version <version>` | Upgrade or roll forward to a specific release |
 
@@ -136,12 +137,39 @@ For safety, `forgexa upgrade` stops any running local daemon before upgrading. I
 
 `forgexa upgrade` supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.
 
+### Automatic Background Upgrade
+
+By default (`auto_upgrade=silent`), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run `forgexa upgrade` yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see [docs/designs/cli-auto-upgrade-design.md](../docs/designs/cli-auto-upgrade-design.md) for the full design). `forgexa upgrade` remains fully available at any time for an immediate manual upgrade or to pin a specific `--target-version` — the two are independent and coexist.
+
+```bash
+# Back to notify-only: check and print a footer notice, but never install automatically
+forgexa config set auto-upgrade notify
+
+# Disable update checks entirely
+forgexa config set auto-upgrade off
+
+# Re-enable silent background installs (the default)
+forgexa config set auto-upgrade silent
+```
+
+| Mode | Check | Silent background install | Footer notice |
+|------|-------|----------------------------|----------------|
+| `silent` (default) | ✅ | ✅ | ✅ (one-time "updated to vX" notice next run) |
+| `notify` | ✅ | ❌ | ✅ |
+| `off` | ❌ | ❌ | ❌ |
+
+A silent install only ever runs for a safe, already-detected install source (pip/pipx — the same sources `forgexa upgrade` supports), never while a local daemon is running (it's skipped and retried on a later invocation instead), never in CI or a non-interactive/`--format json` session, and gives up automatically after 2 consecutive failures for the same target version. Check `forgexa version --status` to see the current mode and the last install attempt's outcome, or `~/.forgexa/upgrade.log` for the raw install output.
+
+`FORGEXA_AUTO_UPGRADE=<silent|notify|off>` overrides the config file for the current shell session; the legacy `FORGEXA_NO_UPDATE_CHECK=1` remains a supported alias for `off`.
+
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `FORGEXA_SERVER_URL` | `http://localhost:8000` | `Server base URL |
 | `FORGEXA_TOKEN` | — | Bearer token (overrides `~/.forgexa/token`) |
+| `FORGEXA_AUTO_UPGRADE` | — | Override `auto_upgrade` (`silent`\|`notify`\|`off`) for this session |
+| `FORGEXA_NO_UPDATE_CHECK` | — | Legacy alias for `FORGEXA_AUTO_UPGRADE=off` |
 
 ## Output Format
 

{forgexa_cli-1.20.5 → forgexa_cli-1.21.0}/README.md

@@ -81,6 +81,7 @@ forgexa board --project <project-id>
 | `forgexa check --agent <name>` | Check a single agent (e.g. `claude`, `codex`, `kimi`) |
 | `forgexa runtimes list` | List your runtimes |
 | `forgexa version` | Show CLI version |
+| `forgexa version --status` | Show auto-upgrade status (mode, active/last success/last failure) |
 | `forgexa upgrade` | Upgrade to the latest CLI release |
 | `forgexa upgrade --target-version <version>` | Upgrade or roll forward to a specific release |
 
@@ -104,12 +105,39 @@ For safety, `forgexa upgrade` stops any running local daemon before upgrading. I
 
 `forgexa upgrade` supports standard PyPI / pipx installs and non-editable local path installs. Editable installs, VCS installs, and other direct URL installs are rejected with a manual upgrade hint.
 
+### Automatic Background Upgrade
+
+By default (`auto_upgrade=silent`), forgexa checks for updates in the background (once every 24h) and silently installs new releases — no need to run `forgexa upgrade` yourself, the same way GitHub Copilot CLI / Claude Code / Kimi Code work (see [docs/designs/cli-auto-upgrade-design.md](../docs/designs/cli-auto-upgrade-design.md) for the full design). `forgexa upgrade` remains fully available at any time for an immediate manual upgrade or to pin a specific `--target-version` — the two are independent and coexist.
+
+```bash
+# Back to notify-only: check and print a footer notice, but never install automatically
+forgexa config set auto-upgrade notify
+
+# Disable update checks entirely
+forgexa config set auto-upgrade off
+
+# Re-enable silent background installs (the default)
+forgexa config set auto-upgrade silent
+```
+
+| Mode | Check | Silent background install | Footer notice |
+|------|-------|----------------------------|----------------|
+| `silent` (default) | ✅ | ✅ | ✅ (one-time "updated to vX" notice next run) |
+| `notify` | ✅ | ❌ | ✅ |
+| `off` | ❌ | ❌ | ❌ |
+
+A silent install only ever runs for a safe, already-detected install source (pip/pipx — the same sources `forgexa upgrade` supports), never while a local daemon is running (it's skipped and retried on a later invocation instead), never in CI or a non-interactive/`--format json` session, and gives up automatically after 2 consecutive failures for the same target version. Check `forgexa version --status` to see the current mode and the last install attempt's outcome, or `~/.forgexa/upgrade.log` for the raw install output.
+
+`FORGEXA_AUTO_UPGRADE=<silent|notify|off>` overrides the config file for the current shell session; the legacy `FORGEXA_NO_UPDATE_CHECK=1` remains a supported alias for `off`.
+
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `FORGEXA_SERVER_URL` | `http://localhost:8000` | `Server base URL |
 | `FORGEXA_TOKEN` | — | Bearer token (overrides `~/.forgexa/token`) |
+| `FORGEXA_AUTO_UPGRADE` | — | Override `auto_upgrade` (`silent`\|`notify`\|`off`) for this session |
+| `FORGEXA_NO_UPDATE_CHECK` | — | Legacy alias for `FORGEXA_AUTO_UPGRADE=off` |
 
 ## Output Format
 

{forgexa_cli-1.20.5 → forgexa_cli-1.21.0}/forgexa_cli/__init__.py

@@ -1,2 +1,2 @@
 """forgexa-cli — Forgexa command-line client."""
-__version__ = "1.20.5"
+__version__ = "1.21.0"

forgexa_cli-1.21.0/forgexa_cli/autoupgrade.py

@@ -0,0 +1,219 @@
+"""Auto-upgrade infrastructure for forgexa-cli.
+
+Holds the pieces that are reusable/testable in isolation: resolving the
+effective ``auto_upgrade`` mode (env var > ``~/.forgexa/config`` > built-in
+default), and the on-disk state/lock files used to coordinate silent
+background installs across concurrent CLI invocations.
+
+The actual "check + maybe install" orchestration lives in ``main.py`` (it
+needs to call ``_build_upgrade_plan()``, daemon helpers, etc. which live
+there); this module only provides the primitives.
+
+See docs/designs/cli-auto-upgrade-design.md for the full design and rationale.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+# ── auto_upgrade mode resolution ──────────────────────────────────────────────
+
+VALID_MODES = ("silent", "notify", "off")
+DEFAULT_MODE = "silent"
+
+# Failure/staleness tuning (see docs/designs/cli-auto-upgrade-design.md §4.7).
+FAILURE_BACKOFF_LIMIT = 2
+ACTIVE_INSTALL_STALE_SECONDS = 30 * 60
+LOCK_STALE_SECONDS = 30 * 60
+
+
+def resolve_auto_upgrade_mode(config: dict) -> str:
+    """Resolve the effective ``auto_upgrade`` mode.
+
+    Precedence: ``FORGEXA_NO_UPDATE_CHECK`` (legacy total kill-switch, wins
+    over everything) > ``FORGEXA_AUTO_UPGRADE`` env var >
+    ``~/.forgexa/config``'s ``auto_upgrade`` key > built-in default
+    (``"notify"``).
+    """
+    if os.environ.get("FORGEXA_NO_UPDATE_CHECK"):
+        return "off"
+    env = os.environ.get("FORGEXA_AUTO_UPGRADE", "").strip().lower()
+    if env in VALID_MODES:
+        return env
+    configured = str(config.get("auto_upgrade") or "").strip().lower()
+    if configured in VALID_MODES:
+        return configured
+    return DEFAULT_MODE
+
+
+def describe_auto_upgrade_source(config: dict) -> str:
+    """Human-readable description of where the effective mode came from.
+
+    Mirrors the precedence order in ``resolve_auto_upgrade_mode`` for
+    display purposes (``forgexa config show``).
+    """
+    if os.environ.get("FORGEXA_NO_UPDATE_CHECK"):
+        return "FORGEXA_NO_UPDATE_CHECK env var"
+    env = os.environ.get("FORGEXA_AUTO_UPGRADE", "").strip().lower()
+    if env in VALID_MODES:
+        return "FORGEXA_AUTO_UPGRADE env var"
+    configured = str(config.get("auto_upgrade") or "").strip().lower()
+    if configured in VALID_MODES:
+        return "~/.forgexa/config"
+    return "built-in default"
+
+
+# ── State file (~/.forgexa/upgrade-state.json) ────────────────────────────────
+#
+# Tracks the outcome of silent background install attempts:
+#   active       — an install currently in progress: {version, started_at}
+#   last_failure — most recent failure: {version, failed_at, attempts}
+#   last_success — most recent success: {version, installed_at, notified}
+
+
+def _state_path() -> Path:
+    return Path.home() / ".forgexa" / "upgrade-state.json"
+
+
+def empty_state() -> dict:
+    return {"active": None, "last_failure": None, "last_success": None}
+
+
+def read_state() -> dict:
+    """Return the upgrade state dict. Never raises; missing/corrupt -> empty shape."""
+    try:
+        data = json.loads(_state_path().read_text())
+        if isinstance(data, dict):
+            state = empty_state()
+            state.update({k: data.get(k) for k in state if k in data})
+            return state
+    except Exception:
+        pass
+    return empty_state()
+
+
+def write_state(state: dict) -> None:
+    """Atomically write the upgrade state. Never raises."""
+    try:
+        path = _state_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(state, indent=2))
+        tmp.replace(path)
+        path.chmod(0o600)
+    except Exception:
+        pass
+
+
+def failure_attempts_for(state: dict, target_version: str) -> int:
+    """How many consecutive failures are recorded for `target_version`.
+
+    Resets to 0 as soon as a different (e.g. newer) target version is being
+    considered, so a fixed release doesn't stay permanently backed off.
+    """
+    failure = state.get("last_failure") or {}
+    if failure.get("version") == target_version:
+        return int(failure.get("attempts") or 0)
+    return 0
+
+
+def has_fresh_active_install(state: dict, target_version: str) -> bool:
+    """Whether an install for `target_version` is already in progress and not stale."""
+    active = state.get("active") or {}
+    if active.get("version") != target_version:
+        return False
+    started_at = active.get("started_at")
+    if not isinstance(started_at, (int, float)):
+        return False
+    return (time.time() - started_at) < ACTIVE_INSTALL_STALE_SECONDS
+
+
+# ── Lock file (~/.forgexa/upgrade.lock) ────────────────────────────────────────
+#
+# Prevents two concurrent CLI invocations from both starting a background
+# install. Content is `{version, pid, started_at}`; staleness is judged by
+# age first, and by whether `pid` is still alive as a secondary signal.
+
+
+def _lock_path() -> Path:
+    return Path.home() / ".forgexa" / "upgrade.lock"
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def _lock_is_stale(path: Path) -> bool:
+    try:
+        payload = json.loads(path.read_text())
+    except Exception:
+        return True  # Unparseable lock content — safe to reclaim.
+
+    pid = payload.get("pid")
+    if isinstance(pid, int) and not _pid_alive(pid):
+        return True
+
+    started_at = payload.get("started_at")
+    if not isinstance(started_at, (int, float)):
+        return True
+    return (time.time() - started_at) >= LOCK_STALE_SECONDS
+
+
+def _write_lock_atomically(path: Path, target_version: str) -> bool:
+    payload = json.dumps(
+        {"version": target_version, "pid": os.getpid(), "started_at": time.time()}
+    ).encode("utf-8")
+    try:
+        fd = os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except OSError:
+        return False
+    try:
+        os.write(fd, payload)
+    finally:
+        os.close(fd)
+    return True
+
+
+def try_acquire_lock(target_version: str) -> bool:
+    """Attempt to atomically create the upgrade lock file.
+
+    Returns True on success (caller must call ``release_lock()`` when done),
+    or False if another (non-stale) install is already in progress. A stale
+    lock is reclaimed automatically. Never raises.
+    """
+    path = _lock_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return False
+
+    if _write_lock_atomically(path, target_version):
+        return True
+
+    if not path.exists() or not _lock_is_stale(path):
+        return False
+
+    # Stale lock — reclaim it. A concurrent racer may win this instead; that's
+    # fine, at most one of us proceeds and the other simply skips this round.
+    try:
+        path.unlink()
+    except OSError:
+        pass
+    return _write_lock_atomically(path, target_version)
+
+
+def release_lock() -> None:
+    try:
+        _lock_path().unlink(missing_ok=True)
+    except OSError:
+        pass

{forgexa_cli-1.20.5 → forgexa_cli-1.21.0}/forgexa_cli/daemon.py

@@ -555,7 +555,7 @@ except (ImportError, ModuleNotFoundError):
 # DAEMON_VERSION is the protocol/logic version of the daemon code.
 # Kept in sync with pyproject.toml version via bump-version.sh.
 # CLIENT_TYPE identifies which packaging/distribution this daemon runs in.
-DAEMON_VERSION = "1.20.5"
+DAEMON_VERSION = "1.21.0"
 
 
 def _detect_client_type() -> str: