tytcli 0.2.0__py3-none-any.whl

tytcli/selfupdate.py

@@ -0,0 +1,639 @@
+"""尽力而为的自更新，查的是解析出来的那个包索引。
+
+这里的每一个设计决定都是刻意的；改动之前请先读完：
+
+* **绝不跟随重定向。** 内网索引会把自己没有托管的包 303 重定向到一个**公网**镜像
+  （``mirrors.ustc.edu.cn``）。跟随它就等于信任来自内网索引之外的版本数据：任何在
+  公共 PyPI 上注册了 ``tytcli`` 的人，都能借此把代码推进每一个安装。只相信来自
+  索引主机的 HTTP 200；3xx 一律读作"该索引上没有发布"。
+* **失败开放（fail open）。** 索引不可达、权限错误、升级坏掉，都绝不能挡住用户
+  真正要跑的那条命令。警告走 stderr；退出码永远由业务命令决定。
+* **有缓存。** 每个间隔（10 分钟，固定）最多一次网络调用，而不是每次调用都查。
+* **索引的解析顺序。** ``TYTCLI_UPDATE_INDEX_URL`` > ``PIP_INDEX_URL`` >
+  pypi.org。继承 pip 的索引，能让检查落在"安装大概就是从那儿来的"那个镜像上，
+  这正是它在企业内网里足够快的原因。
+* **绝不阻塞在 stdin 上。**
+* **re-exec 有界。** 升级成功后会 re-exec 新代码去跑原来那条命令；一个环境变量
+  守卫保证这件事最多发生一次。
+* **只接受纯数字版本。** ``0.2.0rc1`` 绝不会被自动装到 ``0.1.0`` 之上。凡是不能
+  完全匹配 ``\\d+(\\.\\d+)*`` 的一律忽略，所以索引上偶然出现的预发布版无法劫持
+  一次安装。
+
+索引只提供 ``#md5=`` 碎片（没有 sha256），所以在这里无法做有意义的制品完整性校验。
+信任链建立在"索引在内网"与上面那条不跟随重定向的规则之上。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+import httpx
+
+from . import output
+from .errors import ApiError, NetworkError, TytCliError
+
+PACKAGE_NAME = "tytcli"
+
+#: 查新版本时使用的索引。**对所有人都是 pypi.org。**
+#:
+#: 制品只有一份（见 AGENTS.md）：同一批字节由 CI 发到 pypi.org，并镜像到内网索引，
+#: 所以一个默认值对两类使用者都是正确的。而且两者之中只有 pypi.org 是**每个**用户
+#: 都能解析的——索引不可达会让检查永远 fail open（每十分钟一条被缓存的 stderr
+#: 警告，外加一个永远不来的更新），这正是本项目判定为缺陷的"看起来健康其实是坏的"。
+#:
+#: 必须留在内网镜像上的安装请设 ``TYTCLI_UPDATE_INDEX_URL``；``manual_instruction()``
+#: 届时也会指名那个索引，因为它是函数而不是在 import 时就冻结的常量。
+#: 环境里普通的 ``PIP_INDEX_URL`` 同样会被采纳，这样一个处在快速本地镜像后面的用户
+#: 就不必每次检查都付一次到 pypi.org 的往返。空值视为未设置。
+DEFAULT_INDEX_URL = "https://pypi.org/simple/"
+
+#: 两次索引查询之间的秒数。**刻意固定。**
+#:
+#: 这里曾经是 ``DEFAULT_CHECK_INTERVAL_SECONDS``，可用
+#: ``TYTCLI_UPDATE_CHECK_INTERVAL`` 覆盖，并用 ``TYTCLI_NO_UPDATE_CHECK``
+#: （或把间隔设成 ``0``）彻底关掉检查。三者都已删除：产品契约是"始终运行最新版"，
+#: 而一个用户可调的间隔只会让安装悄悄过期、同时看起来一切正常。
+#: 十分钟这个值同时给"网络开销"和"最新能有多旧"封了顶。
+CHECK_INTERVAL_SECONDS = 600.0
+DEFAULT_CHECK_TIMEOUT_SECONDS = 5.0
+UPGRADE_TIMEOUT_SECONDS = 300.0
+
+ENV_TIMEOUT = "TYTCLI_UPDATE_CHECK_TIMEOUT"
+ENV_INDEX = "TYTCLI_UPDATE_INDEX_URL"
+#: 次选索引：pip 自己指向哪里就用哪里。**只读环境变量**，不读 ``pip config``
+#: 配置文件——在这里重新实现 pip 的配置解析，等于去猜一个归 pip 所有的格式。
+#: 不要与 :data:`ENV_INDEX` 混淆：后者是 tytcli 专属的覆盖项，因此优先级更高。
+ENV_PIP_INDEX = "PIP_INDEX_URL"
+#: 索引是被哪个旋钮选中的；会报在 ``upgrade`` 的输出里，这样一个出乎意料的
+#: 查询目标不用靠猜就能解释清楚。
+SOURCE_EXPLICIT = "TYTCLI_UPDATE_INDEX_URL"
+SOURCE_PIP = "PIP_INDEX_URL"
+SOURCE_DEFAULT = "default"
+#: re-exec 的循环守卫：升级后的子进程会设置它，从而不再重复检查。
+#: 前导下划线表示这是内部机制——它不是给用户用的旋钮。
+ENV_REEXEC_GUARD = "_TYTCLI_REEXEC_GUARD"
+#: 内部开关，让测试套件能使每一次 ``run_cli`` 都保持封闭（不联网）。
+#: 刻意不对用户公开：公开的关闭开关已经删掉了，这是唯一能停住钩子的办法，
+#: 而它的名字本身就说明了这一点。
+ENV_HOOK_DISABLED = "_TYTCLI_SKIP_UPDATE_HOOK"
+
+CACHE_APP_DIR = "tytcli"
+CACHE_FILE_NAME = "update-check.json"
+
+#: 匹配 ``tytcli-0.2.0-py3-none-any.whl`` / ``tytcli-0.2.0.tar.gz``。
+#: 版本那一组只允许数字和点，这正是把预发布版挡在外面的机制。
+_ARTIFACT_RE = re.compile(
+    r"tytcli-(?P<version>\d+(?:\.\d+)*)(?:-py[^\s\"'<>]*\.whl|\.tar\.gz)"
+)
+
+
+# --------------------------------------------------------------------------- #
+# versions
+# --------------------------------------------------------------------------- #
+
+
+def parse_version(text: str) -> tuple[int, ...] | None:
+    """Parse a plain numeric version, or return ``None`` if it is not one.
+
+    Deliberately rejects prereleases (``1.0rc1``), epochs (``1!1.0``) and
+    anything else PEP 440 allows: auto-upgrade must never install one.
+    """
+    value = text.strip()
+    if not value or not re.fullmatch(r"\d+(?:\.\d+)*", value):
+        return None
+    return tuple(int(part) for part in value.split("."))
+
+
+def compare_versions(left: str, right: str) -> int:
+    """Return -1/0/1. Unparseable versions compare as equal (no upgrade)."""
+    a, b = parse_version(left), parse_version(right)
+    if a is None or b is None:
+        return 0
+    width = max(len(a), len(b))
+    a_padded = a + (0,) * (width - len(a))
+    b_padded = b + (0,) * (width - len(b))
+    return (a_padded > b_padded) - (a_padded < b_padded)
+
+
+def is_newer(candidate: str, current: str) -> bool:
+    return compare_versions(candidate, current) > 0
+
+
+# --------------------------------------------------------------------------- #
+# index query
+# --------------------------------------------------------------------------- #
+
+
+def _resolve_index(env_map: Mapping[str, str]) -> tuple[str, str]:
+    """Return ``(url, source)`` for the index to query.
+
+    Precedence: ``TYTCLI_UPDATE_INDEX_URL`` > ``PIP_INDEX_URL`` > pypi.org.
+    The first *non-blank* value wins: an exported-but-empty variable must not
+    degrade into the URL ``/`` (which is what a naive ``.get(name, default)``
+    does, since only a missing key falls back).
+    """
+    for name, source in ((ENV_INDEX, SOURCE_EXPLICIT), (ENV_PIP_INDEX, SOURCE_PIP)):
+        raw = (env_map.get(name) or "").strip()
+        if raw:
+            return raw.rstrip("/") + "/", source
+    return DEFAULT_INDEX_URL, SOURCE_DEFAULT
+
+
+def index_url(environ: Mapping[str, str] | None = None) -> str:
+    """Base URL of the PEP 503 index to query (trailing slash guaranteed)."""
+    return _resolve_index(os.environ if environ is None else environ)[0]
+
+
+def index_source(environ: Mapping[str, str] | None = None) -> str:
+    """Which knob chose the index: an env var name, or ``"default"``."""
+    return _resolve_index(os.environ if environ is None else environ)[1]
+
+
+def latest_version_from_html(html: str) -> str | None:
+    """Pick the highest numeric version out of a PEP 503 simple index page."""
+    best: str | None = None
+    for match in _ARTIFACT_RE.finditer(html):
+        version = match.group("version")
+        if best is None or is_newer(version, best):
+            best = version
+    return best
+
+
+def fetch_latest_version(
+    *, index: str | None = None, timeout: float = DEFAULT_CHECK_TIMEOUT_SECONDS
+) -> str:
+    """Query the index and return the newest version, or ``""`` if unknown.
+
+    Raises ``NetworkError`` on transport failure and ``ApiError`` when the index
+    answers with something that is not a usable listing. ``""`` means "the
+    package is not published on this index", which callers treat as no-op.
+    """
+    base = index or index_url()
+    url = f"{base}{PACKAGE_NAME}/"
+    try:
+        # follow_redirects=False is the security control; see module docstring.
+        with httpx.Client(timeout=timeout, follow_redirects=False) as client:
+            response = client.get(url)
+    except httpx.TimeoutException as exc:
+        raise NetworkError(
+            f"版本检查超时（{timeout}s）：{url}",
+            code="NETWORK_TIMEOUT",
+            details={"url": url, "timeout_seconds": timeout},
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise NetworkError(
+            f"版本检查失败：{type(exc).__name__}",
+            code="NETWORK_ERROR",
+            details={"url": url, "error_type": type(exc).__name__},
+        ) from exc
+
+    if response.status_code in (301, 302, 303, 307, 308):
+        # Redirect == not hosted internally. Do NOT follow: the target is a
+        # public mirror, and trusting it would allow a name-squatting attack.
+        return ""
+    if response.status_code == 404:
+        return ""
+    if response.status_code != 200:
+        raise ApiError(
+            f"索引返回 HTTP {response.status_code}",
+            code="INDEX_HTTP_ERROR",
+            details={"url": url, "http_status": response.status_code},
+        )
+
+    return latest_version_from_html(response.text) or ""
+
+
+# --------------------------------------------------------------------------- #
+# cache
+# --------------------------------------------------------------------------- #
+
+
+def cache_path(environ: Mapping[str, str] | None = None) -> Path:
+    env_map = os.environ if environ is None else environ
+    xdg = env_map.get("XDG_CACHE_HOME", "").strip()
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".cache"
+    return base / CACHE_APP_DIR / CACHE_FILE_NAME
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Outcome of a version check."""
+
+    latest_version: str  # "" means unknown / not published
+    checked_at: float
+    source: str  # index | cache | skipped | error
+    index_url: str
+
+    @property
+    def checked_age_seconds(self) -> float:
+        return max(0.0, time.time() - self.checked_at)
+
+    def is_newer_than(self, current: str) -> bool:
+        return bool(self.latest_version) and is_newer(self.latest_version, current)
+
+
+def _read_cache(path: Path) -> dict[str, Any] | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    # json.loads() is Any; isinstance narrows it to dict[Unknown, Unknown],
+    # which would poison every caller's types.
+    return cast("dict[str, Any]", data)
+
+
+def _write_cache(path: Path, result: CheckResult) -> None:
+    payload = {
+        "checked_at": result.checked_at,
+        "latest_version": result.latest_version,
+        "index_url": result.index_url,
+    }
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload), encoding="utf-8")
+    except OSError:
+        # A cache we cannot write is not an error; we simply re-check next time.
+        pass
+
+
+def check_interval() -> float:
+    """Seconds between index queries: :data:`CHECK_INTERVAL_SECONDS`, always.
+
+    Takes no environment argument because there is nothing left to read -- the
+    old ``TYTCLI_UPDATE_CHECK_INTERVAL`` / ``TYTCLI_NO_UPDATE_CHECK`` overrides
+    were removed. A test that wants a different cadence patches this function.
+    """
+    return CHECK_INTERVAL_SECONDS
+
+
+def check_timeout(environ: Mapping[str, str] | None = None) -> float:
+    env_map = os.environ if environ is None else environ
+    raw = env_map.get(ENV_TIMEOUT)
+    if raw is None or not raw.strip():
+        return DEFAULT_CHECK_TIMEOUT_SECONDS
+    try:
+        value = float(raw)
+    except ValueError:
+        return DEFAULT_CHECK_TIMEOUT_SECONDS
+    return value if value > 0 else DEFAULT_CHECK_TIMEOUT_SECONDS
+
+
+def check_for_update(
+    current_version: str,
+    *,
+    force: bool = False,
+    environ: Mapping[str, str] | None = None,
+) -> CheckResult:
+    """Return the latest known version, using the cache when it is fresh enough.
+
+    Never raises: every failure degrades to ``latest_version=""`` so the caller
+    can fail open. Use :func:`fetch_latest_version` when the error matters.
+    """
+    env_map = dict(os.environ if environ is None else environ)
+    index = index_url(env_map)
+    interval = check_interval()
+    path = cache_path(env_map)
+    now = time.time()
+
+    if not force:
+        cached = _read_cache(path)
+        if cached is not None and cached.get("index_url") == index:
+            try:
+                checked_at = float(cached.get("checked_at", 0))
+            except (TypeError, ValueError):
+                checked_at = 0.0
+            if now - checked_at < interval:
+                version = str(cached.get("latest_version") or "")
+                return CheckResult(version, checked_at, "cache", index)
+
+    try:
+        version = fetch_latest_version(
+            index=index, timeout=check_timeout(env_map)
+        )
+    except TytCliError:
+        # Cache the failure as well. Without this, an unreachable index would
+        # make *every* invocation pay the full connect timeout, which is exactly
+        # when the user is least able to wait. With it, the TTL applies to
+        # failures too: one warning and one slow command per interval.
+        failed = CheckResult("", now, "error", index)
+        _write_cache(path, failed)
+        return failed
+
+    result = CheckResult(version, now, "index", index)
+    _write_cache(path, result)
+    return result
+
+
+def record_check(
+    latest_version: str,
+    *,
+    index: str | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> CheckResult:
+    """Persist a check result so the implicit hook can reuse it.
+
+    Used by the explicit ``upgrade`` command, which calls
+    :func:`fetch_latest_version` directly so that failures surface as proper
+    error codes instead of being swallowed the way the implicit check swallows
+    them.
+    """
+    env_map = dict(os.environ if environ is None else environ)
+    base = index or index_url(env_map)
+    result = CheckResult(latest_version, time.time(), "index", base)
+    _write_cache(cache_path(env_map), result)
+    return result
+
+
+# --------------------------------------------------------------------------- #
+# upgrade planning
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class UpgradePlan:
+    """How to upgrade this installation."""
+
+    kind: str  # uv-tool | venv-pip | venv-uv | manual
+    argv: list[str]
+    reason: str
+
+    @property
+    def can_upgrade(self) -> bool:
+        return bool(self.argv)
+
+
+def _executable_path() -> Path | None:
+    raw = sys.argv[0] if sys.argv and sys.argv[0] else None
+    if not raw:
+        return None
+    try:
+        return Path(raw).resolve()
+    except OSError:  # pragma: no cover - defensive
+        return None
+
+
+def _is_uv_tool_install(path: Path | None) -> bool:
+    if path is None:
+        return False
+    text = str(path).replace(os.sep, "/")
+    return "/uv/tools/" in text
+
+
+def _venv_python() -> Path | None:
+    if sys.prefix == sys.base_prefix:
+        return None  # not a virtualenv
+    name = "python.exe" if os.name == "nt" else "python"
+    candidate = Path(sys.prefix) / ("Scripts" if os.name == "nt" else "bin") / name
+    return candidate if candidate.exists() else None
+
+
+def _venv_pip() -> Path | None:
+    if sys.prefix == sys.base_prefix:
+        return None
+    name = "pip.exe" if os.name == "nt" else "pip"
+    candidate = Path(sys.prefix) / ("Scripts" if os.name == "nt" else "bin") / name
+    return candidate if candidate.exists() else None
+
+
+def plan_upgrade(*, index: str | None = None) -> UpgradePlan:
+    """Detect how tytcli was installed and return the matching upgrade command.
+
+    Order matters: a uv-tool install is also a virtualenv, so the ``/uv/tools/``
+    path check must come first. ``uv``-created venvs ship **without pip**, hence
+    the ``venv-uv`` fallback. Anything else (system site-packages) is refused
+    rather than upgraded, because it would need sudo or would pollute a shared
+    interpreter.
+    """
+    base = (index or index_url()).rstrip("/")
+
+    if _is_uv_tool_install(_executable_path()):
+        uv = shutil.which("uv")
+        if uv:
+            return UpgradePlan(
+                kind="uv-tool",
+                argv=[uv, "tool", "upgrade", PACKAGE_NAME, "--default-index", base],
+                reason="uv tool 安装",
+            )
+        return UpgradePlan(
+            kind="manual",
+            argv=[],
+            reason="检测到 uv tool 安装，但 PATH 上找不到 uv",
+        )
+
+    python = _venv_python()
+    pip = _venv_pip()
+    if python is not None and pip is not None:
+        return UpgradePlan(
+            kind="venv-pip",
+            argv=[str(pip), "install", "-U", "--index-url", base, PACKAGE_NAME],
+            reason="虚拟环境（含 pip）",
+        )
+
+    if python is not None:
+        uv = shutil.which("uv")
+        if uv:
+            return UpgradePlan(
+                kind="venv-uv",
+                argv=[
+                    uv, "pip", "install",
+                    "--python", str(python),
+                    "-U", "--default-index", base, PACKAGE_NAME,
+                ],
+                reason="虚拟环境（无 pip，uv 创建的 venv 不带 pip）",
+            )
+        return UpgradePlan(
+            kind="manual",
+            argv=[],
+            reason="虚拟环境内既没有 pip，PATH 上也没有 uv",
+        )
+
+    return UpgradePlan(
+        kind="manual",
+        argv=[],
+        reason=(
+            "看起来安装在系统/共享解释器的 site-packages 中。"
+            "拒绝自动升级：那需要提权或会污染共享环境"
+        ),
+    )
+
+
+def manual_instruction(environ: Mapping[str, str] | None = None) -> str:
+    """Commands a user can run to upgrade by hand.
+
+    Deliberately a function rather than a module constant: the index honours
+    ``TYTCLI_UPDATE_INDEX_URL``, and a constant frozen at import time would
+    keep naming the default even for a user who overrode it.
+    """
+    index = index_url(environ)
+    return (
+        f"pip install -U --index-url {index} {PACKAGE_NAME}\n"
+        f"  或：uv tool install --default-index {index} {PACKAGE_NAME}"
+    )
+
+
+def run_upgrade(plan: UpgradePlan) -> str:
+    """Execute the plan. Returns combined output; raises on failure."""
+    if not plan.can_upgrade:
+        raise ApiError(
+            f"无法自动升级：{plan.reason}",
+            code="UPDATE_UNSUPPORTED",
+            details={"kind": plan.kind, "reason": plan.reason, "hint": manual_instruction()},
+        )
+    try:
+        # argv is assembled by plan_upgrade() from shutil.which() results and
+        # fixed literals -- never from user input -- so no shell is involved.
+        completed = subprocess.run(
+            plan.argv,
+            capture_output=True,
+            text=True,
+            timeout=UPGRADE_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except OSError as exc:
+        raise ApiError(
+            f"升级命令无法执行：{exc}",
+            code="UPDATE_FAILED",
+            details={"kind": plan.kind, "argv0": plan.argv[0]},
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise ApiError(
+            f"升级超时（{UPGRADE_TIMEOUT_SECONDS}s）",
+            code="UPDATE_TIMEOUT",
+            details={"kind": plan.kind},
+        ) from exc
+
+    output = f"{completed.stdout}\n{completed.stderr}".strip()
+    if completed.returncode != 0:
+        raise ApiError(
+            f"升级失败（退出码 {completed.returncode}）",
+            code="UPDATE_FAILED",
+            details={
+                "kind": plan.kind,
+                "returncode": completed.returncode,
+                "output": output[-2000:],
+            },
+        )
+    return output
+
+
+# --------------------------------------------------------------------------- #
+# implicit hook used by cli.main()
+# --------------------------------------------------------------------------- #
+
+
+def _warn(message: str) -> None:
+    print(f"警告：{message}", file=sys.stderr)
+
+
+def reexec_after_upgrade(argv: list[str]) -> None:
+    """Replace this process with the freshly installed code.
+
+    Runs the module rather than ``sys.argv[0]``: the entry-point script may have
+    been rewritten by the upgrade, and ``-m`` also works when tytcli was launched
+    that way in the first place.
+    """
+    environ = dict(os.environ)
+    environ[ENV_REEXEC_GUARD] = "1"
+    os.execve(sys.executable, [sys.executable, "-m", "tytcli.cli", *argv], environ)
+
+
+def should_skip_implicit_check(argv: list[str], environ: Mapping[str, str] | None = None) -> str | None:
+    """Return a reason to skip the implicit check, or ``None`` to proceed."""
+    env_map = os.environ if environ is None else environ
+    if env_map.get(ENV_REEXEC_GUARD):
+        return "already re-exec'd after an upgrade"
+    if env_map.get(ENV_HOOK_DISABLED):
+        # Internal, test-suite only. Users have no opt-out by design.
+        return f"{ENV_HOOK_DISABLED} set (internal)"
+    if not argv:
+        return "no command given"
+    if {"-h", "--help", "--version"} & set(argv):
+        return "help/version request"
+    # `tytcli help` is a pure local read of the bundled docs; phoning the index
+    # first would make reading documentation depend on the network.
+    if argv[0] == "help":
+        return "help command"
+    # The explicit command does its own check and must not be run twice.
+    if any(token == "upgrade" for token in argv[:2]):
+        return "explicit upgrade command"
+    return None
+
+
+def maybe_self_update(
+    current_version: str, argv: list[str], *, environ: Mapping[str, str] | None = None
+) -> bool:
+    """Check, upgrade and re-exec if a newer version exists. Fail open.
+
+    Returns ``True`` only in the (unusual) case where it returns at all after a
+    successful upgrade — normally :func:`reexec_after_upgrade` replaces the
+    process and this never returns.
+
+    The whole body is wrapped: this hook runs before ``main()``'s own error
+    handling, so an exception escaping here (e.g. ``os.execve`` failing) would
+    surface as a raw traceback and break the JSON-on-stdout contract. "Fail
+    open" has to cover bugs in the updater itself, not just network failures.
+    """
+    try:
+        return _maybe_self_update(current_version, argv, environ=environ)
+    except Exception as exc:  # last resort: the hook must never break a command
+        _warn(
+            f"版本检查出现未预期错误（{type(exc).__name__}: {exc}），"
+            f"继续使用当前版本 {current_version}。"
+        )
+        return False
+
+
+def _maybe_self_update(
+    current_version: str, argv: list[str], *, environ: Mapping[str, str] | None = None
+) -> bool:
+    env_map = dict(os.environ if environ is None else environ)
+    if should_skip_implicit_check(argv, env_map) is not None:
+        return False
+
+    result = check_for_update(current_version, environ=env_map)
+    if result.source == "error":
+        # Fail open, but not silently: the user chose to be told.
+        _warn(f"版本检查失败（索引不可达），继续使用当前版本 {current_version}。")
+    if not result.is_newer_than(current_version):
+        return False
+
+    plan = plan_upgrade(index=result.index_url)
+    if not plan.can_upgrade:
+        # A newer version exists but this installation cannot take it. The
+        # command's own JSON document carries that as __tytcli_hint__ (same
+        # channel as the wechat field hint) instead of a second stderr copy:
+        # two channels for one fact is how automation gets lied to.
+        output.set_pending_hint(
+            f"发现新版本 {result.latest_version}（当前 {current_version}），"
+            f"但当前安装形式无法自动升级（{plan.reason}）。"
+            f"手动升级：{manual_instruction()}"
+        )
+        return False
+
+    try:
+        run_upgrade(plan)
+    except TytCliError as exc:
+        # Fail open: the user's command still runs on the current version, and
+        # the document explains that an upgrade was attempted and failed.
+        output.set_pending_hint(
+            f"发现新版本 {result.latest_version}（当前 {current_version}），"
+            f"自动升级失败（{exc.code}：{exc.message}）。"
+            f"运行 `tytcli upgrade` 重试，或检查包索引是否可达。"
+        )
+        return False
+
+    _warn(f"已升级到 {result.latest_version}，重新执行原命令。")
+    reexec_after_upgrade(argv)
+    return True  # pragma: no cover - execve does not return