| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338 |
- """The plugin update-check cadence: read-only, receipt-surfaced.
- Runs at gateway start + the periodic tick when
- ``plugins.auto_update_check_hours`` (default 24, 0 disables) says it's
- due, writes a plugin-check receipt (pm.receipt, kind 'plugin-check'),
- and logs ONE actionable line when updates exist. Applying updates
- stays explicit — ``plugins.auto_apply: true`` (default false) opts into
- unattended apply for catalog and tracked git plugins, scan-gated like cmd_update.
- Pure, injectable clock/check/update seams for hermetic tests.
- """
- from __future__ import annotations
- import threading
- import time
- from pathlib import Path
- from typing import Callable, Optional
- _MARKERS_DIR = "plugin-update-checks"
- _DEFAULT_INTERVAL_HOURS = 24
- def _marker_path() -> Path:
- """The last-run marker, resolved per call (tests monkeypatch
- get_hermes_home). Derivation only — NO mkdir: a due-check or any
- read path must not create user state."""
- from hermes_constants import get_hermes_home
- return get_hermes_home() / _MARKERS_DIR / "last-run"
- def _results_path() -> Path:
- """The last check's per-plugin results, next to the marker (derivation only)."""
- return _marker_path().parent / "results.json"
- def snapshot_installs(plugins_dir: Path) -> dict:
- """The install records an update check is about to compare against. Take it BEFORE the check runs:
- a record read afterwards may already include an update that finished during the check."""
- from hermes_cli.plugins_provenance import read_sidecar_rows
- return read_sidecar_rows(plugins_dir)
- def record_check_results(results: list, checked_installs: dict) -> None:
- """Persist a completed check so surfaces that list plugins (the Desktop Plugins tab) can show an
- update without a network call per listing. Each row carries the install record it was checked
- against (*checked_installs*, from :func:`snapshot_installs` before the check), so a later reader
- can tell whether the result still applies. Never raises."""
- import json
- from utils import atomic_write_text
- try:
- rows = []
- for r in results:
- row = r.to_json() if hasattr(r, "to_json") else dict(r)
- rows.append({**row, "checked_install": _install_fingerprint(checked_installs.get(row.get("name")))})
- atomic_write_text(_markers_dir() / "results.json", json.dumps(rows, indent=2) + "\n")
- except (OSError, TypeError, ValueError):
- pass
- def _install_fingerprint(record) -> dict | None:
- """The parts of an install record an update check depends on."""
- if not isinstance(record, dict):
- return None
- return {"source": record.get("source"), "revision": record.get("revision"), "pinned": record.get("pinned") is True}
- def cached_git_updates(install_metadata: dict) -> dict[str, str]:
- """``{plugin name: what the update moves to}`` (a commit or a feed version) for git installs the last
- check found behind. A result is dropped once the install it was checked against changed (updated,
- reinstalled from another source, or pinned with ``--ref``), so Desktop never offers an update that
- already landed or one ``update`` would refuse."""
- import json
- try:
- rows = json.loads(_results_path().read_text(encoding="utf-8-sig"))
- except (OSError, ValueError):
- return {}
- out: dict[str, str] = {}
- for row in rows if isinstance(rows, list) else ():
- if not isinstance(row, dict) or row.get("class") != "git" or row.get("update_available") is not True:
- continue
- current = _install_fingerprint(install_metadata.get(row.get("name")))
- if current and not current["pinned"] and current == row.get("checked_install") and row.get("latest"):
- out[str(row["name"])] = str(row["latest"])
- return out
- def _markers_dir() -> Path:
- """The markers dir, created on demand — WRITE paths only."""
- d = _marker_path().parent
- d.mkdir(parents=True, exist_ok=True)
- return d
- def check_interval_hours(config_get: Callable | None = None) -> float:
- """plugins.auto_update_check_hours; 0 disables; default 24."""
- if config_get is None:
- config_get = _default_config_get
- try:
- value = config_get("plugins", "auto_update_check_hours")
- except Exception:
- return _DEFAULT_INTERVAL_HOURS
- if value is None:
- return _DEFAULT_INTERVAL_HOURS
- try:
- hours = float(value)
- except (TypeError, ValueError):
- return _DEFAULT_INTERVAL_HOURS
- return max(0.0, hours)
- def auto_apply_enabled(config_get: Callable | None = None) -> bool:
- if config_get is None:
- config_get = _default_config_get
- try:
- return bool(config_get("plugins", "auto_apply"))
- except Exception:
- return False
- def _default_config_get(section: str, key: str):
- try:
- from hermes_cli.config import cfg_get, load_config_readonly
- return cfg_get(load_config_readonly(), section, key, default=None)
- except Exception:
- return None
- def check_due(now: Optional[float] = None, interval_hours: Optional[float] = None,
- config_get: Callable | None = None) -> bool:
- """The clock gate: last-run marker vs the interval."""
- if interval_hours is None:
- interval_hours = check_interval_hours(config_get)
- if interval_hours <= 0:
- return False
- now = time.time() if now is None else now
- marker = _marker_path()
- try:
- last = marker.stat().st_mtime
- except OSError:
- return True
- return (now - last) >= interval_hours * 3600
- #: Minimal singleflight for one home: two gateway ticks overlapping in
- #: this process (boot pass + periodic tick) must not double-fetch or
- #: double-write receipts. A plain non-blocking lock — not a manager.
- _tick_lock = threading.Lock()
- def run_scheduled_check(
- *,
- run_checks_fn: Callable[..., list],
- plugins_dir: Path,
- apply_updates_fn: Optional[Callable[[str], None]] = None,
- log=None,
- config_get: Callable | None = None,
- now: Optional[float] = None,
- ) -> Optional[list]:
- """One cadence tick: gate → check → receipt → (opt-in) apply.
- Returns the check results, or None when not due / disabled / another
- tick is already in flight. NEVER raises — a cadence failure is
- logged, never fatal.
- """
- import logging
- if log is None:
- log = logging.getLogger(__name__)
- if not check_due(now=now, config_get=config_get):
- return None
- if not _tick_lock.acquire(blocking=False):
- log.debug("plugin update check already in flight — skipping tick")
- return None
- try:
- return _run_check_locked(
- run_checks_fn=run_checks_fn,
- plugins_dir=plugins_dir,
- apply_updates_fn=apply_updates_fn,
- log=log,
- config_get=config_get,
- )
- finally:
- _tick_lock.release()
- def _auto_apply(updates: list, checked_installs: dict, apply_updates_fn: Callable[[str], None], log) -> None:
- """Apply each update row the opt-in tick may move. A catalog install held with ``--ref`` is left
- where the user put it. A widened catalog pin is a pending review, not a failure: one line naming
- the command that walks it, no traceback every tick; other refusals are one line too."""
- from hermes_cli.plugins_auto_update import HELD_WITH_REF, HeldWithRef, held_with_ref
- from hermes_cli.plugins_cmd import PluginOperationError
- from hermes_cli.plugins_cmd_catalog import RepinConsentRequired
- for r in updates:
- if getattr(r, "klass", "") not in ("git", "catalog"):
- continue
- if held_with_ref(checked_installs.get(r.name)):
- log.info("plugin %s not auto-updated: %s", r.name, HELD_WITH_REF.format(name=r.name))
- continue
- try:
- apply_updates_fn(r.name)
- except HeldWithRef as exc: # held with --ref while the check ran
- log.info("plugin %s not auto-updated: %s", r.name, exc)
- except RepinConsentRequired:
- log.info("plugin %s has an update that needs your review: run `hermes plugins update %s`",
- r.name, r.name)
- except PluginOperationError as exc:
- log.warning("auto-apply of %s not applied: %s", r.name, exc)
- except (Exception, SystemExit):
- log.warning("auto-apply of %s failed", r.name, exc_info=True)
- def _run_check_locked(
- *,
- run_checks_fn: Callable[..., list],
- plugins_dir: Path,
- apply_updates_fn: Optional[Callable[[str], None]],
- log,
- config_get: Callable | None = None,
- ) -> list:
- check_ok = True
- warning = ""
- checked_installs: dict = {}
- try:
- checked_installs = snapshot_installs(plugins_dir)
- results = run_checks_fn(plugins_dir)
- except Exception:
- warning = "plugin update check failed"
- log.warning(warning, exc_info=True)
- results = []
- check_ok = False
- if check_ok:
- record_check_results(results, checked_installs)
- try:
- from pm import receipt
- token = receipt.begin("plugin-check")
- receipt.record_plugin_checks(results)
- if warning:
- receipt.record_warning(warning)
- updates = [r for r in results if getattr(r, "update_available", None) is True]
- receipt.finalize("failed" if not check_ok else "updates-available" if updates else "ok",
- exit_code=0 if check_ok else 1, token=token)
- except Exception:
- log.debug("plugin-check receipt write failed", exc_info=True)
- # ONE actionable line (a log, not a system-prompt mutation — cache safe)
- updates = [r for r in results if getattr(r, "update_available", None) is True]
- needs_fixing = [r for r in results if getattr(r, "needs_fixing", None)]
- if updates:
- names = ", ".join(r.name for r in updates)
- log.info(
- "plugin updates available: %s — run `hermes plugins check-updates` "
- "and `hermes plugins update <name>`",
- names,
- )
- if needs_fixing:
- names = ", ".join(r.name for r in needs_fixing)
- log.warning(
- "plugin update_url mismatches need attention: %s — run "
- "`hermes plugins trust-update-url <name>` after review",
- names,
- )
- # Opt-in unattended apply: the classes `hermes plugins update` can move (catalog re-pins to the
- # reviewed sha, tracked git pulls), scan-gated by the update path itself, which also refuses a
- # widened catalog pin or a too-new requires_hermes without a terminal. Pinned/manual/drift/pip
- # are never auto-applied (their update_available is False/None or their class excludes it).
- if apply_updates_fn and updates and auto_apply_enabled(config_get):
- _auto_apply(updates, checked_installs, apply_updates_fn, log)
- # stamp the marker AFTER a completed run (even a failed one — a
- # failing check retrying every tick would hammer the network)
- try:
- marker = _markers_dir() / "last-run"
- marker.write_text(str(int(time.time())), encoding="utf-8")
- except OSError:
- pass
- return results
- # ---------------------------------------------------------------------------
- # the production caller: real seams for the gateway boot/housekeeping tick
- # ---------------------------------------------------------------------------
- def maybe_run_gateway_check(
- *,
- run_checks_fn: Optional[Callable[..., list]] = None,
- apply_updates_fn: Optional[Callable[[str], None]] = None,
- plugins_dir: Optional[Path] = None,
- log=None,
- now: Optional[float] = None,
- ) -> Optional[list]:
- """The tick every gateway boot / housekeeping pass calls.
- Fills in the REAL seams ``run_scheduled_check`` leaves injectable:
- the same read-only ``plugins_updates.run_checks`` the manual
- ``hermes plugins check-updates`` uses (urllib feed fetch, git
- ls-remote, PyPI latest), the real plugins dir, and the manual
- ``hermes plugins update <name>`` flow as the opt-in apply path —
- auto-apply rides the identical security/consent/scan pipeline.
- Returns the check results, or None when not due / disabled. Due-gated
- by ``plugins.auto_update_check_hours`` (0 disables); a network error
- costs one warning and a stamped marker — never an apply.
- """
- if plugins_dir is None:
- from hermes_cli import plugins_cmd
- plugins_dir = plugins_cmd._plugins_dir()
- if run_checks_fn is None:
- # ONE shared network-default implementation — plugins_updates
- # owns default_fetch / default_ls_remote / _default_pypi_latest;
- # the manual `hermes plugins check-updates` passes the same
- # defaults. No boilerplate re-derivation here.
- from hermes_cli.plugins_updates import run_checks
- run_checks_fn = run_checks
- if apply_updates_fn is None:
- # update_one with no terminal, refusals raised (cmd_update would turn them into an exit)
- from hermes_cli import plugins_auto_update
- apply_updates_fn = plugins_auto_update.apply_unattended
- return run_scheduled_check(
- run_checks_fn=run_checks_fn,
- plugins_dir=plugins_dir,
- apply_updates_fn=apply_updates_fn,
- log=log,
- now=now,
- )
|