alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/adapters/git_watcher.py

@@ -0,0 +1,457 @@
+"""GitWatcher - ambient signal adapter for git repository activity.
+
+Observes one or more local git repositories and publishes ``local.signal``
+events for commits and branch switches. Uses ``watchdog`` to tail the
+per-branch ref files under ``.git/refs/heads/`` and the symbolic ``.git/HEAD``
+pointer, because those change exactly when the user commits (``refs/heads/<br>``
+is rewritten) or switches branches (``HEAD`` is rewritten).
+
+Signals
+-------
+
+* ``kind = "git_commit"`` - a branch ref advanced. Payload::
+
+      {
+          "repo":     "/abs/path/to/repo",
+          "branch":   "main",
+          "sha":      "abc123...",
+          "previous": "def456..." | None,
+      }
+
+* ``kind = "git_branch_switch"`` - the HEAD pointer moved to a different
+  branch. Payload::
+
+      {
+          "repo":     "/abs/path/to/repo",
+          "branch":   "feature/foo",
+          "previous": "main",
+      }
+
+Both are published on the ``local.signal`` topic for the eventual egress
+producer. The runtime itself does *not* post them back to the DO - that is
+the egress producer's job in W2.2d.
+
+Design notes
+------------
+
+* **One observer per repo.** Each configured repo gets a dedicated watchdog
+  ``Observer`` so that a misbehaving filesystem event on one repo does not
+  block another. For typical developer machines this is ~1-3 observers.
+* **Debounce on ref changes.** Git writes refs atomically via rename, which
+  fires both ``on_created`` and ``on_modified`` in rapid succession. We
+  debounce by caching the last-seen SHA per ref and only publishing when it
+  changes.
+* **Thread boundary.** ``watchdog`` callbacks run on the observer's own
+  thread. We marshal onto the asyncio loop via ``loop.call_soon_threadsafe``
+  before publishing to the bus - the bus is *not* thread-safe.
+* **Autodetect CWD.** When ``repo_paths`` is empty and the current working
+  directory is a git repo, the adapter watches the CWD. This is the common
+  case on a developer laptop where the user runs ``alter-runtime daemon``
+  from inside their main workspace.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import re as _re
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from alter_runtime.config import DaemonConfig
+from alter_runtime.daemon import Component
+from alter_runtime.subscribers.bus import EventBus
+
+__all__ = ["GitWatcher"]
+
+logger = logging.getLogger("alter_runtime.adapters.git_watcher")
+
+EGRESS_TOPIC: str = "local.signal"
+
+#: Branch-name shape gate (Pentest 2026-04-26, MEDIUM). Git itself imposes
+#: tighter rules (see ``check-ref-format(1)``), but a watchdog-driven file
+#: rename can land arbitrary bytes here if an attacker plants a malicious
+#: file under ``.git/refs/heads/``. We accept the conservative subset that
+#: covers every legitimate branch name we expect on disk and reject the
+#: rest before they reach the bus and any downstream consumers (DO ingest,
+#: status-bar widgets, etc.).
+
+_BRANCH_NAME_RE = _re.compile(r"^[A-Za-z0-9_./-]+$")
+
+
+def _is_safe_branch_name(branch: str) -> bool:
+    """Return True when ``branch`` matches the allowed branch shape.
+
+    Additional gates beyond the regex (mirroring ``check-ref-format(1)``):
+    reject any ``..`` sequence so a planted ref file can't traverse
+    upward, reject leading ``/`` / ``-`` / ``.``, and reject trailing
+    ``/`` / ``.``.
+    """
+    if not branch or len(branch) > 255:
+        return False
+    if not _BRANCH_NAME_RE.match(branch):
+        return False
+    if ".." in branch:
+        return False
+    if branch.startswith(("/", "-", ".")):
+        return False
+    if branch.endswith(("/", ".")):
+        return False
+    return True
+
+
+@dataclass
+class _WatchedRepo:
+    """Bookkeeping for one watched repository."""
+
+    path: Path
+    git_dir: Path
+    #: Last-seen SHAs keyed by branch name, for debouncing redundant fs events.
+    branch_shas: dict[str, str] = field(default_factory=dict)
+    #: Last-seen HEAD branch name, for detecting branch switches.
+    head_branch: str | None = None
+    observer: Any | None = None
+
+
+class GitWatcher(Component):
+    """Watches git repos and publishes commit / branch-switch signals.
+
+    Parameters
+    ----------
+    config:
+        Loaded :class:`DaemonConfig` (currently unused but kept for symmetry
+        with the other components and future knobs like ``git_watch_paths``).
+    bus:
+        Shared :class:`EventBus` - signals are published on ``local.signal``.
+    repo_paths:
+        Explicit list of repository paths to watch. If empty, the adapter
+        autodetects the current working directory when it's a git repo and
+        falls back to no-op otherwise.
+    """
+
+    name = "git_watcher"
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        bus: EventBus,
+        repo_paths: list[Path] | None = None,
+    ) -> None:
+        self._config = config
+        self._bus = bus
+        self._explicit_paths = repo_paths
+        self._stop_event = asyncio.Event()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._repos: list[_WatchedRepo] = []
+
+    # ------------------------------------------------------------------
+    # Component lifecycle
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        self._loop = asyncio.get_running_loop()
+        repos = self._resolve_repos()
+        if not repos:
+            logger.info("git_watcher no repositories to watch - idle")
+            await self._stop_event.wait()
+            return
+
+        try:
+            from watchdog.events import FileSystemEventHandler  # noqa: F401
+            from watchdog.observers import Observer
+        except ImportError:
+            logger.warning("watchdog not installed - git_watcher disabled")
+            await self._stop_event.wait()
+            return
+
+        for repo in repos:
+            self._bootstrap_repo_state(repo)
+            observer = Observer()
+            handler = _GitRefHandler(self, repo)
+            refs_dir = repo.git_dir / "refs" / "heads"
+            if refs_dir.exists():
+                observer.schedule(handler, str(refs_dir), recursive=True)
+            head_file = repo.git_dir / "HEAD"
+            if head_file.exists():
+                observer.schedule(handler, str(repo.git_dir), recursive=False)
+            observer.daemon = True
+            observer.start()
+            repo.observer = observer
+            self._repos.append(repo)
+            logger.info(
+                "git_watcher observing repo=%s initial_branch=%s initial_shas=%s",
+                repo.path,
+                repo.head_branch,
+                {k: v[:7] for k, v in repo.branch_shas.items()},
+            )
+
+        try:
+            await self._stop_event.wait()
+        finally:
+            for repo in self._repos:
+                if repo.observer is not None:
+                    with contextlib.suppress(Exception):
+                        repo.observer.stop()
+                        repo.observer.join(timeout=2.0)
+            logger.info("git_watcher stopped")
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+
+    # ------------------------------------------------------------------
+    # Repo discovery + initial state
+    # ------------------------------------------------------------------
+
+    def _resolve_repos(self) -> list[_WatchedRepo]:
+        paths: list[Path] = []
+        if self._explicit_paths:
+            paths = [Path(p).expanduser().resolve() for p in self._explicit_paths]
+        else:
+            # Autodetect from CWD - resolve() so symlinked workspaces don't
+            # confuse the symlink check below.
+            cwd = Path.cwd().resolve()
+            git_dir = cwd / ".git"
+            if git_dir.is_dir():
+                paths = [cwd]
+
+        repos: list[_WatchedRepo] = []
+        for path in paths:
+            git_dir = path / ".git"
+            # Pentest 2026-04-26 (MEDIUM): refuse to register a watch when
+            # ``.git`` is a symlink. Watchdog follows symlinks transparently,
+            # which would let an attacker drop a symlinked .git into a CWD
+            # the daemon scans and trick the watcher into observing - and
+            # publishing signals from - a directory tree outside the
+            # operator's repo set. Worktrees and gitlinks (file ``.git`` with
+            # ``gitdir: <path>`` content) are handled separately by git
+            # itself; refusing the symlink case is the conservative gate.
+            if git_dir.is_symlink():
+                logger.warning(
+                    "git_watcher refusing symlinked .git path=%s -> %s",
+                    git_dir,
+                    git_dir.resolve(strict=False),
+                )
+                continue
+            if not git_dir.is_dir():
+                logger.warning("git_watcher skipping non-repo path=%s", path)
+                continue
+            repos.append(_WatchedRepo(path=path, git_dir=git_dir))
+        return repos
+
+    def _bootstrap_repo_state(self, repo: _WatchedRepo) -> None:
+        """Prime ``branch_shas`` and ``head_branch`` from current refs.
+
+        Without this, the first commit after startup would publish a
+        ``git_commit`` for every existing ref because the ``branch_shas``
+        cache starts empty.
+        """
+        refs_dir = repo.git_dir / "refs" / "heads"
+        if refs_dir.is_dir():
+            for ref_file in _iter_ref_files(refs_dir):
+                branch = _branch_name_from_ref(refs_dir, ref_file)
+                sha = _read_ref(ref_file)
+                if sha:
+                    repo.branch_shas[branch] = sha
+
+        head_file = repo.git_dir / "HEAD"
+        if head_file.exists():
+            repo.head_branch = _read_head_branch(head_file)
+
+    # ------------------------------------------------------------------
+    # Watchdog callbacks (thread → asyncio bridge)
+    # ------------------------------------------------------------------
+
+    def _on_ref_change(self, repo: _WatchedRepo, event_path: str) -> None:
+        """Called on the watchdog thread when a ref file changes."""
+        loop = self._loop
+        if loop is None or loop.is_closed():
+            return
+        loop.call_soon_threadsafe(
+            lambda: asyncio.create_task(self._handle_ref_change_async(repo, event_path))
+        )
+
+    async def _handle_ref_change_async(self, repo: _WatchedRepo, event_path: str) -> None:
+        """Runs on the asyncio loop - inspect the ref and publish if changed."""
+        path = Path(event_path)
+        refs_dir = repo.git_dir / "refs" / "heads"
+        head_file = repo.git_dir / "HEAD"
+
+        try:
+            if path == head_file or path.name == "HEAD":
+                new_branch = _read_head_branch(head_file) if head_file.exists() else None
+                if new_branch and new_branch != repo.head_branch:
+                    # Pentest 2026-04-26 (MEDIUM): branch names traverse the
+                    # bus to the DO ingest path. Reject anything that doesn't
+                    # match the conservative shape gate before publishing -
+                    # don't update head_branch on reject so the next valid
+                    # change still fires.
+                    if not _is_safe_branch_name(new_branch):
+                        logger.warning(
+                            "git_watcher rejecting unsafe HEAD branch name=%r repo=%s",
+                            new_branch,
+                            repo.path,
+                        )
+                        return
+                    previous = repo.head_branch
+                    repo.head_branch = new_branch
+                    await self._publish(
+                        "git_branch_switch",
+                        {
+                            "repo": str(repo.path),
+                            "branch": new_branch,
+                            "previous": previous,
+                        },
+                    )
+                return
+
+            # Ref file under .git/refs/heads/
+            try:
+                path.relative_to(refs_dir)
+            except ValueError:
+                return
+
+            if not path.exists() or not path.is_file():
+                return
+            branch = _branch_name_from_ref(refs_dir, path)
+            # Pentest 2026-04-26 (MEDIUM): sanitise the branch name before it
+            # reaches the bus. _branch_name_from_ref derives from the on-disk
+            # ref filename which a same-UID attacker can plant arbitrarily.
+            if not _is_safe_branch_name(branch):
+                logger.warning(
+                    "git_watcher rejecting unsafe ref branch name=%r repo=%s",
+                    branch,
+                    repo.path,
+                )
+                return
+            sha = _read_ref(path)
+            if not sha:
+                return
+            previous = repo.branch_shas.get(branch)
+            if previous == sha:
+                return  # debounce
+            repo.branch_shas[branch] = sha
+            await self._publish(
+                "git_commit",
+                {
+                    "repo": str(repo.path),
+                    "branch": branch,
+                    "sha": sha,
+                    "previous": previous,
+                },
+            )
+        except Exception as exc:  # pragma: no cover
+            logger.warning("git_watcher ref change handling failed: %s", exc)
+
+    async def _publish(self, kind: str, payload: dict[str, Any]) -> None:
+        logger.info(
+            "git_watcher publishing kind=%s repo=%s branch=%s",
+            kind,
+            payload.get("repo"),
+            payload.get("branch"),
+        )
+        await self._bus.publish(
+            EGRESS_TOPIC,
+            {"kind": kind, "payload": payload, "source": "git_watcher"},
+        )
+
+    # ------------------------------------------------------------------
+    # Test introspection
+    # ------------------------------------------------------------------
+
+    @property
+    def watched_repos(self) -> list[_WatchedRepo]:
+        return list(self._repos)
+
+
+# ---------------------------------------------------------------------------
+# watchdog event handler - sits between the observer thread and the loop
+# ---------------------------------------------------------------------------
+
+
+class _GitRefHandler:
+    """Tiny wrapper - watchdog's FileSystemEventHandler is imported lazily
+    inside :meth:`GitWatcher.run` so that installs without watchdog can still
+    import ``git_watcher``. This class shims the interface without subclassing
+    so type checkers don't demand the import at module-load time.
+    """
+
+    def __init__(self, watcher: GitWatcher, repo: _WatchedRepo) -> None:
+        self._watcher = watcher
+        self._repo = repo
+        # Cache the thread ID we were constructed on for debug logging.
+        self._construct_thread = threading.get_ident()
+
+    # watchdog calls these via duck typing; no base class required.
+    def dispatch(self, event: Any) -> None:
+        if getattr(event, "is_directory", False):
+            return
+        # Drop pure-read events. Modern watchdog versions (>=2.x with
+        # IN_OPEN/IN_CLOSE_NOWRITE in the default mask) emit a
+        # FileOpenedEvent + FileClosedNoWriteEvent for every open-and-read
+        # of a watched file. ``.git/HEAD`` and the active branch ref are
+        # opened thousands of times per second by ``git status`` callers
+        # (IDE git plugins, statusline scripts, parallel CC sessions), and
+        # without this filter every read scheduled an ``asyncio.create_task``
+        # via ``_on_ref_change`` - flooding the loop with no-op handles
+        # that grew RSS by ~10MB/s and tripped OOM in <5min on a busy repo.
+        kind = type(event).__name__
+        if kind in ("FileOpenedEvent", "FileClosedNoWriteEvent"):
+            return
+        src = getattr(event, "src_path", None)
+        dest = getattr(event, "dest_path", None)
+        # Fire on whichever path exists after the event (move target for
+        # renames, src for create/modify).
+        target = dest or src
+        if not isinstance(target, str):
+            return
+        self._watcher._on_ref_change(self._repo, target)
+
+
+# ---------------------------------------------------------------------------
+# Ref file helpers
+# ---------------------------------------------------------------------------
+
+
+def _iter_ref_files(refs_dir: Path):
+    """Yield every ref file under ``refs_dir`` recursively."""
+    for root, _dirs, files in os.walk(refs_dir):
+        for fname in files:
+            yield Path(root) / fname
+
+
+def _branch_name_from_ref(refs_dir: Path, ref_file: Path) -> str:
+    """Return the branch name given a path under ``.git/refs/heads/``."""
+    try:
+        return str(ref_file.relative_to(refs_dir))
+    except ValueError:
+        return ref_file.name
+
+
+def _read_ref(ref_file: Path) -> str | None:
+    """Read a ref file and return the SHA, or None on read failure."""
+    try:
+        return ref_file.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _read_head_branch(head_file: Path) -> str | None:
+    """Return the branch HEAD points at, or None if detached / unreadable.
+
+    ``.git/HEAD`` is either ``ref: refs/heads/<branch>`` for an attached head
+    or a bare SHA for a detached head.
+    """
+    try:
+        content = head_file.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+    if content.startswith("ref:"):
+        _, _, ref = content.partition("ref:")
+        ref = ref.strip()
+        if ref.startswith("refs/heads/"):
+            return ref[len("refs/heads/") :]
+    return None

alter_runtime/adapters/household/__init__.py

@@ -0,0 +1,29 @@
+"""Household substrate adapters (Phase 2 physical-substrate widening).
+
+Scaffolded under the Wave-A Tapo pilot for ~blake's homeserver gear:
+
+* :mod:`workshop_tools` (Eco-12) — per-plug Wh fingerprint via MQTT.
+* :mod:`compost` (Eco-9) — pile-temp curve via MQTT, plate-tag filtered.
+* :mod:`tapo_ecosystem` (Eco-14) — hub-level multi-parameter composition.
+* :mod:`self_hoster` (Eco-15) — own-host systemd + filesystem polling.
+
+All four conform to D-PROV-1 (RATIFIED 2026-05-13) and the IaI 5-clause
+overlay; each ships a hard-coded Clause-4 banlist refused at trait-emit
+time.  Bands only — raw Wh / temp / event counts never cross the daemon
+boundary upward.
+
+NOT auto-wired into :mod:`alter_runtime.daemon` startup; activation is a
+follow-up wave once the stub specs in
+``.repos/internal/02-Technical-Strategy/phase2-wave2-stub-specs-pack-2026-05-27.md``
+land their implementation pass.
+"""
+
+from alter_runtime.adapters.household._base import (
+    EventBusSubscriberBase,
+    PassiveLanPollerBase,
+)
+
+__all__ = [
+    "EventBusSubscriberBase",
+    "PassiveLanPollerBase",
+]

alter_runtime/adapters/household/_base.py

@@ -0,0 +1,138 @@
+"""Shared base classes for the household adapter family.
+
+Two adapter shapes per the Phase-2 cross-pattern catalogue
+(``.repos/internal/02-Technical-Strategy/phase2-substrate-cross-pattern-catalogue-2026-05-19.md``):
+
+* :class:`EventBusSubscriberBase` — subscribes to the in-process
+  :class:`~alter_runtime.subscribers.bus.EventBus` for events the
+  household-bridge subscriber (or a future HA/MQTT shim) publishes from
+  the maker's LAN.  Used by ``workshop_tools``, ``compost``, and
+  ``tapo_ecosystem``.
+* :class:`PassiveLanPollerBase` — polls a local resource (own host,
+  paired LAN device) on a fixed cadence.  Used by ``self_hoster``
+  (degenerate-LAN: the daemon polls its own host).
+
+Both extend :class:`~alter_runtime.daemon.Component` so the supervisor
+can run them as long-lived tasks once wired in.  They deliberately stop
+short of imposing topic taxonomy, payload shape, or storage choice —
+those are per-adapter concerns.
+
+D-PROV-1 (RATIFIED 2026-05-13) governs all consumers; IaI 5-clause map
+sits in the per-adapter ``traits.py`` modules so the banlist is
+co-located with the trait emit site that enforces it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import abstractmethod
+from typing import Any
+
+from alter_runtime.config import DaemonConfig
+from alter_runtime.daemon import Component
+from alter_runtime.subscribers.bus import EventBus
+
+__all__ = [
+    "EventBusSubscriberBase",
+    "PassiveLanPollerBase",
+]
+
+
+class EventBusSubscriberBase(Component):
+    """Base for adapters that subscribe to in-process bus events.
+
+    Subclasses set :attr:`subscribe_topics` (one or more topic strings)
+    and implement :meth:`handle_event`.  The base wires subscribe /
+    unsubscribe symmetry around the supervisor lifecycle and shields the
+    supervisor from subscriber exceptions (the bus already does this,
+    but adapter-side logging is more useful for debugging).
+    """
+
+    name: str = "household_event_bus_subscriber"
+    #: Topics this adapter subscribes to.  Set on the subclass.
+    subscribe_topics: tuple[str, ...] = ()
+
+    def __init__(self, config: DaemonConfig, bus: EventBus) -> None:
+        self._config = config
+        self._bus = bus
+        self._stop_event = asyncio.Event()
+        self._logger = logging.getLogger(f"alter_runtime.adapters.household.{self.name}")
+
+    async def run(self) -> None:
+        if not self.subscribe_topics:
+            self._logger.info("%s no subscribe_topics declared — idle", self.name)
+            await self._stop_event.wait()
+            return
+
+        for topic in self.subscribe_topics:
+            self._bus.subscribe(topic, self._dispatch)
+        self._logger.info("%s subscribed topics=%s", self.name, list(self.subscribe_topics))
+
+        try:
+            await self._stop_event.wait()
+        finally:
+            for topic in self.subscribe_topics:
+                self._bus.unsubscribe(topic, self._dispatch)
+            self._logger.info("%s stopped", self.name)
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+
+    async def _dispatch(self, payload: Any) -> None:
+        try:
+            await self.handle_event(payload)
+        except Exception as exc:  # pragma: no cover — defensive
+            self._logger.warning("%s handle_event raised: %s", self.name, exc)
+
+    @abstractmethod
+    async def handle_event(self, payload: Any) -> None:
+        """Process one bus event.  Subclass responsibility."""
+
+
+class PassiveLanPollerBase(Component):
+    """Base for adapters that poll a local resource on a fixed cadence.
+
+    Subclasses set :attr:`poll_interval_seconds` and implement
+    :meth:`poll_once`.  The base supervises the poll loop, sleeps
+    between iterations, and exits cleanly on shutdown.
+
+    ``self_hoster`` (Eco-15) is the canonical degenerate-LAN consumer
+    — the daemon polls its own host's systemd D-Bus + filesystem; no
+    network calls cross the loopback interface.
+    """
+
+    name: str = "household_passive_lan_poller"
+    #: Default 6 hours per the self-hoster stub spec.
+    poll_interval_seconds: float = 6 * 60 * 60
+
+    def __init__(self, config: DaemonConfig) -> None:
+        self._config = config
+        self._stop_event = asyncio.Event()
+        self._logger = logging.getLogger(f"alter_runtime.adapters.household.{self.name}")
+
+    async def run(self) -> None:
+        self._logger.info(
+            "%s starting poll loop interval=%.0fs", self.name, self.poll_interval_seconds
+        )
+        try:
+            while not self._stop_event.is_set():
+                try:
+                    await self.poll_once()
+                except Exception as exc:  # pragma: no cover — defensive
+                    self._logger.warning("%s poll_once raised: %s", self.name, exc)
+                try:
+                    await asyncio.wait_for(
+                        self._stop_event.wait(), timeout=self.poll_interval_seconds
+                    )
+                except asyncio.TimeoutError:
+                    pass
+        finally:
+            self._logger.info("%s stopped", self.name)
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+
+    @abstractmethod
+    async def poll_once(self) -> None:
+        """Run one poll cycle.  Subclass responsibility."""

alter_runtime/adapters/household/compost/__init__.py

@@ -0,0 +1,17 @@
+"""Compost substrate adapter (Eco-9).
+
+Subscribes to MQTT topic glob ``tapo/temp_humid/+/state``, filters to
+devices whose member-attested plate tag is ``"compost"``, and computes
+a 30-day temperature-curve patience trait (band).  Persists to
+``~/.local/share/alter-runtime/compost.db`` (mode 600).
+
+Spec: ``.repos/internal/02-Technical-Strategy/compost-substrate-adapter-2026-05-19.md``
+"""
+
+from alter_runtime.adapters.household.compost.adapter import CompostAdapter
+from alter_runtime.adapters.household.compost.traits import (
+    CLAUSE_4_BANLIST,
+    CompostTraits,
+)
+
+__all__ = ["CLAUSE_4_BANLIST", "CompostAdapter", "CompostTraits"]