hap-cli 0.8.4__tar.gz → 0.8.5__tar.gz

{hap_cli-0.8.4 → hap_cli-0.8.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.4
+Version: 0.8.5
 Summary: CLI harness for MingDAO HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0
@@ -313,6 +313,13 @@ body, and a redacted `Authorization` header (first 16 chars). `password`
 and other sensitive keys are masked. `HAP_LOG_LEVEL=DEBUG` temporarily
 overrides the persisted level.
 
+### update — keep the CLI current
+
+| Command | Description |
+|---|---|
+| `update` | Check PyPI for a newer release and upgrade in place, using the same tool the CLI was installed with (pip / pipx / uv) |
+| `update --check` | Only report whether a newer version exists, without installing |
+
 ---
 
 ## Default app & organization

{hap_cli-0.8.4/hap_cli → hap_cli-0.8.5}/README.md

@@ -284,6 +284,13 @@ body, and a redacted `Authorization` header (first 16 chars). `password`
 and other sensitive keys are masked. `HAP_LOG_LEVEL=DEBUG` temporarily
 overrides the persisted level.
 
+### update — keep the CLI current
+
+| Command | Description |
+|---|---|
+| `update` | Check PyPI for a newer release and upgrade in place, using the same tool the CLI was installed with (pip / pipx / uv) |
+| `update --check` | Only report whether a newer version exists, without installing |
+
 ---
 
 ## Default app & organization

{hap_cli-0.8.4 → hap_cli-0.8.5/hap_cli}/README.md

@@ -284,6 +284,13 @@ body, and a redacted `Authorization` header (first 16 chars). `password`
 and other sensitive keys are masked. `HAP_LOG_LEVEL=DEBUG` temporarily
 overrides the persisted level.
 
+### update — keep the CLI current
+
+| Command | Description |
+|---|---|
+| `update` | Check PyPI for a newer release and upgrade in place, using the same tool the CLI was installed with (pip / pipx / uv) |
+| `update --check` | Only report whether a newer version exists, without installing |
+
 ---
 
 ## Default app & organization

{hap_cli-0.8.4 → hap_cli-0.8.5}/hap_cli/README_CN.md

@@ -260,6 +260,13 @@ hap --json worksheet record list WORKSHEET_ID
 
 日志默认写入 `~/.hap-cli/hap-cli.log`，10 MB × 3 滚动。开启后每次 API 调用以 `INFO` 级别记录 URL、请求体、响应体，以及脱敏后的 `Authorization` 头（仅前 16 字符）；`password` 等敏感字段会被自动打码。临时调试可设 `HAP_LOG_LEVEL=DEBUG`。
 
+### update — 升级 CLI
+
+| 命令 | 说明 |
+|---|---|
+| `update` | 检查 PyPI 上的最新版本，有新版则用安装时的工具（pip / pipx / uv）原地升级 |
+| `update --check` | 只检查是否有新版本，不安装 |
+
 ---
 
 ## 默认应用与组织

{hap_cli-0.8.4 → hap_cli-0.8.5}/hap_cli/__init__.py

@@ -1,3 +1,3 @@
 """CLI harness for MingDAO HAP (hap-cli)."""
 
-__version__ = "0.8.4"
+__version__ = "0.8.5"

hap_cli-0.8.5/hap_cli/__main__.py

@@ -0,0 +1,11 @@
+"""Allow ``python -m hap_cli`` — used by the detached background
+update child (``hap update --background``), which is spawned with
+``sys.executable -m hap_cli`` so it always runs in the same
+environment as the parent process regardless of how the ``hap``
+console script was installed.
+"""
+
+from hap_cli.hap_cli import main
+
+if __name__ == "__main__":
+    main()

hap_cli-0.8.5/hap_cli/commands/update_cmd.py

@@ -0,0 +1,101 @@
+"""CLI command for self-updating hap-cli from PyPI.
+
+The hidden ``--background`` flag is the entry point for the detached
+child process spawned by the exit-time hook in ``hap_cli.py`` — it is
+internal plumbing and intentionally absent from ``--help`` and docs.
+"""
+
+import time
+
+import click
+
+from hap_cli.context import pass_context
+from hap_cli.core import update as upd
+
+
+@click.command("update")
+@click.option(
+    "--check",
+    "check_only",
+    is_flag=True,
+    help="Only check whether a newer version exists; do not install.",
+)
+@click.option("--background", is_flag=True, hidden=True)
+@pass_context
+def update(ctx, check_only, background):
+    """Upgrade hap-cli to the latest version from PyPI.
+
+    Checks for a newer release and installs it using the same tool the
+    CLI was installed with (pip, pipx, or uv). Installs that are not
+    managed from PyPI are left untouched.
+    """
+    if background:
+        # Detached child: silent check-and-upgrade; results go to the
+        # state file and are surfaced on the next foreground run.
+        upd.run_background_update()
+        return
+
+    from hap_cli import __version__
+
+    kind = upd.get_install_kind()
+    if kind in ("editable", "unknown"):
+        ctx.output(
+            {"current": __version__, "install": kind, "updated": False},
+            lambda d: click.echo(
+                "This copy of hap-cli is not managed from PyPI "
+                f"(current version {__version__}) — nothing to update."
+            ),
+        )
+        return
+
+    latest = upd.fetch_latest_version()
+    if latest is None:
+        ctx.handle_error(Exception("Could not reach PyPI to check for updates."))
+        return
+
+    if not upd.is_newer(latest, __version__):
+        upd.save_state(
+            {
+                "last_check_at": time.time(),
+                "latest_version": latest,
+                "last_result": "up_to_date",
+                "notified": True,
+            }
+        )
+        ctx.output(
+            {"current": __version__, "latest": latest, "updated": False},
+            lambda d: click.echo(
+                f"hap-cli {__version__} is already the latest version."
+            ),
+        )
+        return
+
+    if check_only:
+        ctx.output(
+            {"current": __version__, "latest": latest, "updated": False},
+            lambda d: click.echo(
+                f"A newer version is available: {latest} "
+                f"(current {__version__}). Run `hap update` to upgrade."
+            ),
+        )
+        return
+
+    click.echo(f"Upgrading hap-cli {__version__} -> {latest} ...")
+    ok, output = upd.perform_upgrade(kind)
+    upd.save_state(
+        {
+            "last_check_at": time.time(),
+            "latest_version": latest,
+            "last_result": "upgraded" if ok else "upgrade_failed",
+            "upgraded_to": latest if ok else None,
+            "notified": True,
+        }
+    )
+    if ok:
+        ctx.output(
+            {"current": __version__, "latest": latest, "updated": True},
+            lambda d: click.echo(f"Upgraded to hap-cli {latest}."),
+        )
+    else:
+        click.echo(output, err=True)
+        ctx.handle_error(Exception(f"Upgrade to {latest} failed."))

hap_cli-0.8.5/hap_cli/core/update.py

@@ -0,0 +1,294 @@
+"""Self-update support for hap-cli.
+
+Two entry paths share this module:
+
+- ``hap update`` — synchronous, user-invoked check/upgrade.
+- ``hap update --background`` — hidden; spawned as a detached child
+  process when a command exits and the last check is older than
+  ``UPDATE_CHECK_INTERVAL_SECONDS``. It checks PyPI, auto-upgrades if
+  newer, and records the outcome in the state file so the *next* run
+  can surface a one-line notice.
+
+Editable installs (PEP 660 ``direct_url.json`` with
+``dir_info.editable: true``) and unrecognized install origins disable
+the feature entirely — they are by definition not managed via PyPI.
+"""
+
+import json
+import logging
+import os
+import re
+import subprocess
+import sys
+import time
+from typing import Any, Optional
+
+import requests
+
+logger = logging.getLogger("hap_cli.update")
+
+PYPI_PACKAGE = "hap-cli"
+PYPI_JSON_URL = f"https://pypi.org/pypi/{PYPI_PACKAGE}/json"
+
+# Deliberately short while the tool is iterating quickly; once releases
+# stabilize, bump this in a regular release (it ships with the code, so
+# every upgrade can retune the cadence).
+UPDATE_CHECK_INTERVAL_SECONDS = 3600
+
+# Only final releases (digits and dots) are auto-upgrade candidates;
+# pre/dev/post markers ("0.9.0rc1", "1.0.dev2") are skipped.
+_FINAL_RELEASE_RE = re.compile(r"^\d+(\.\d+)*$")
+
+
+def _state_file():
+    # Resolve lazily through the session module so tests (and
+    # HAP_CLI_HOME) that repoint CONFIG_DIR are honored.
+    from hap_cli.core import session
+
+    return session.CONFIG_DIR / "update_check.json"
+
+
+# ── Install-kind detection ───────────────────────────────────────────────
+
+
+def get_install_kind() -> str:
+    """Classify how this copy of hap-cli was installed.
+
+    Returns one of ``editable`` / ``pip`` / ``pipx`` / ``uv`` /
+    ``unknown``. Only ``pip`` / ``pipx`` / ``uv`` are upgradable from
+    PyPI; the other two disable the update feature.
+    """
+    import importlib.metadata
+
+    try:
+        dist = importlib.metadata.distribution(PYPI_PACKAGE)
+        direct_url_text = dist.read_text("direct_url.json")
+    except Exception as e:
+        logger.warning("install-kind detection failed: %s", e)
+        return "unknown"
+
+    if direct_url_text:
+        try:
+            direct_url = json.loads(direct_url_text)
+        except ValueError:
+            return "unknown"
+        if direct_url.get("dir_info", {}).get("editable"):
+            return "editable"
+        # Installed from a direct URL/path but not editable — we don't
+        # know how to keep it current, so stay hands-off.
+        return "unknown"
+
+    prefix = sys.prefix.replace(os.sep, "/")
+    if "pipx/venvs" in prefix:
+        return "pipx"
+    if "uv/tools" in prefix:
+        return "uv"
+    return "pip"
+
+
+def build_upgrade_command(kind: str) -> Optional[list]:
+    """Upgrade argv for an install kind, or None if not upgradable."""
+    if kind == "pip":
+        return [sys.executable, "-m", "pip", "install", "--upgrade", PYPI_PACKAGE]
+    if kind == "pipx":
+        return ["pipx", "upgrade", PYPI_PACKAGE]
+    if kind == "uv":
+        return ["uv", "tool", "upgrade", PYPI_PACKAGE]
+    return None
+
+
+# ── Version handling ─────────────────────────────────────────────────────
+
+
+def _version_tuple(version: str) -> tuple:
+    return tuple(int(part) for part in version.split("."))
+
+
+def is_newer(latest: str, current: str) -> bool:
+    """True if ``latest`` is strictly newer than ``current``."""
+    try:
+        return _version_tuple(latest) > _version_tuple(current)
+    except ValueError:
+        logger.warning(
+            "cannot compare versions latest=%r current=%r", latest, current
+        )
+        return False
+
+
+def fetch_latest_version(timeout: int = 5) -> Optional[str]:
+    """Latest final (non-prerelease, non-yanked) version on PyPI.
+
+    Returns None on any network/parse error — callers treat that as
+    "couldn't check", never as an error surfaced to the user.
+    """
+    from hap_cli.core.logger import format_response_for_log
+
+    logger.info("HAP GET %s params={} Authorization=<none>", PYPI_JSON_URL)
+    try:
+        response = requests.get(PYPI_JSON_URL, timeout=timeout)
+        logger.info(
+            "HAP GET %s -> %d %s",
+            PYPI_JSON_URL,
+            response.status_code,
+            format_response_for_log(getattr(response, "text", "") or ""),
+        )
+        response.raise_for_status()
+        payload = response.json()
+    except Exception as e:
+        logger.warning("PyPI version check failed: %s", e)
+        return None
+
+    candidates = []
+    for version, files in (payload.get("releases") or {}).items():
+        if not _FINAL_RELEASE_RE.match(version):
+            continue
+        if not files or all(f.get("yanked") for f in files):
+            continue
+        candidates.append(version)
+    if not candidates:
+        return None
+    return max(candidates, key=_version_tuple)
+
+
+# ── State file ───────────────────────────────────────────────────────────
+
+
+def load_state() -> dict:
+    """Read the update-check state; empty dict if missing/corrupt."""
+    try:
+        with open(_state_file(), encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except FileNotFoundError:
+        return {}
+    except Exception as e:
+        logger.warning("corrupt update state file, resetting: %s", e)
+        return {}
+
+
+def save_state(state: dict) -> None:
+    """Atomically persist the update-check state."""
+    path = _state_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+# ── Background check orchestration ───────────────────────────────────────
+
+
+def maybe_spawn_background_check() -> None:
+    """Spawn a detached background update check if it is due.
+
+    Called when a CLI command finishes. The timestamp is bumped
+    *before* spawning so rapid consecutive commands cannot stack
+    duplicate children — at worst a failed child costs one interval.
+    """
+    kind = get_install_kind()
+    if kind in ("editable", "unknown"):
+        return
+
+    state = load_state()
+    last = state.get("last_check_at") or 0
+    now = time.time()
+    if now - last < UPDATE_CHECK_INTERVAL_SECONDS:
+        return
+
+    state["last_check_at"] = now
+    save_state(state)
+
+    try:
+        subprocess.Popen(
+            [sys.executable, "-m", "hap_cli", "update", "--background"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        logger.info("spawned background update check (install kind: %s)", kind)
+    except Exception as e:
+        logger.warning("failed to spawn background update check: %s", e)
+
+
+def perform_upgrade(kind: str) -> tuple:
+    """Run the upgrade command for ``kind``. Returns (ok, output)."""
+    cmd = build_upgrade_command(kind)
+    if cmd is None:
+        return False, f"no upgrade command for install kind {kind!r}"
+    logger.info("running upgrade command: %s", " ".join(cmd))
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=600
+        )
+    except Exception as e:
+        logger.error("upgrade command failed to run: %s", e)
+        return False, str(e)
+    output = (proc.stdout or "") + (proc.stderr or "")
+    logger.info("upgrade command exited %d", proc.returncode)
+    return proc.returncode == 0, output
+
+
+def run_background_update() -> None:
+    """Body of the hidden ``hap update --background`` child process.
+
+    Silent by design: outcomes go to the state file (surfaced by the
+    next foreground run) and the log, never to the terminal.
+    """
+    from hap_cli import __version__
+
+    state = load_state()
+    state["last_check_at"] = time.time()
+
+    latest = fetch_latest_version()
+    if latest is None:
+        state["last_result"] = "check_failed"
+        save_state(state)
+        return
+
+    state["latest_version"] = latest
+    if not is_newer(latest, __version__):
+        state["last_result"] = "up_to_date"
+        save_state(state)
+        return
+
+    ok, output = perform_upgrade(get_install_kind())
+    if ok:
+        state["last_result"] = "upgraded"
+        state["upgraded_to"] = latest
+    else:
+        state["last_result"] = "upgrade_failed"
+        state["error"] = output[-500:]
+        logger.error("background upgrade to %s failed: %s", latest, output)
+    state["notified"] = False
+    save_state(state)
+
+
+def consume_startup_notice() -> Optional[str]:
+    """One-shot user notice from the last background run, if any.
+
+    Returns the message and marks it notified so it is shown exactly
+    once. Silent results (check_failed / up_to_date) return None.
+    """
+    state = load_state()
+    if state.get("notified", True):
+        return None
+
+    result = state.get("last_result")
+    if result == "upgraded":
+        msg = (
+            f"hap-cli was auto-upgraded to {state.get('upgraded_to')} "
+            "(takes effect from this run)."
+        )
+    elif result == "upgrade_failed":
+        latest = state.get("latest_version") or "a newer version"
+        msg = (
+            f"Automatic upgrade to {latest} failed — "
+            "run `hap update` to upgrade manually."
+        )
+    else:
+        return None
+
+    state["notified"] = True
+    save_state(state)
+    return msg

{hap_cli-0.8.4 → hap_cli-0.8.5}/hap_cli/hap_cli.py

@@ -41,6 +41,11 @@ from hap_cli.commands.region_cmd import region
 from hap_cli.commands.icon_cmd import icon
 from hap_cli.commands.upload_cmd import upload
 from hap_cli.commands.app_editor_cmd import app_editor
+from hap_cli.commands.update_cmd import update as update_cmd
+from hap_cli.core.update import (
+    consume_startup_notice,
+    maybe_spawn_background_check,
+)
 
 
 def clone_group(source, *, name=None, hidden=False):
@@ -71,6 +76,18 @@ def cli(ctx, json_mode, profile):
     ctx.obj.json_mode = json_mode
     ctx.obj.profile = profile
 
+    # Self-update plumbing. Both halves are local-file-only on the hot
+    # path: the notice reads a small JSON state file, and the spawn hook
+    # only forks a detached child when the last check is older than the
+    # interval (the child does the actual network I/O). Skipped for
+    # `update` itself (it manages the state directly) and `repl`
+    # (cli() re-runs per REPL line).
+    notice = consume_startup_notice()
+    if notice:
+        click.echo(notice, err=True)
+    if ctx.invoked_subcommand not in ("update", "repl"):
+        ctx.call_on_close(maybe_spawn_background_check)
+
 
 # Register command groups
 app.add_command(clone_group(role, name="role"))
@@ -127,6 +144,7 @@ cli.add_command(icon)
 cli.add_command(upload)
 cli.add_command(config_group)
 cli.add_command(app_editor)
+cli.add_command(update_cmd)
 
 
 # Hidden top-level alias for the old `hap completion` command. The