Files
Teknium a6efd813d3 fix(plugins): unattended updates re-check the hold and the widened surface at the mutation boundary
- 2.1 hold recorded during the check: update_one/dashboard_update_user_plugin(unattended=True) re-read
  the install record under the per-plugin update lock and skip a --ref hold (HeldWithRef / held);
  _install_plugin_core takes the same lock, so an install --ref cannot publish between the re-check
  and the updater's publication.
- 2.2 custom Git widening: the unattended gate compares the staged candidate's surface (tools, hooks,
  capabilities, ...) with the installed one before publication (git pull and subdirectory re-clone)
  and returns needs_review; a named update still applies it.
- /plugins update <name|all|--yes> refuses extra arguments with a usage line instead of updating
  every plugin.
- hermes plugins update (cmd_update_all) skips catalog installs held with --ref, like every other
  Update all.
2026-11-04 21:58:12 -08:00

339 lines
13 KiB
Python

"""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,
)