recx-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{recx_cli-0.1.0 → recx_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: recx-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Validator for RECX.yaml manifests: the recx check command.
 Project-URL: Homepage, https://github.com/jbmv/recx
 Project-URL: Repository, https://github.com/jbmv/recx
@@ -75,6 +75,14 @@ anything listed can be reused without asking.
 
 Then add the GitHub topic `recx` to the repository, so the daily index finds it promptly.
 
+The plugin's hook runs when a session or one of its subagents stops (Claude Code's Stop and
+SubagentStop events). It blocks on an invalid manifest, and it reminds, without blocking, when
+files under a module's `path` changed during the session while RECX.yaml did not. A commit can
+record that module entries were checked against its tree with a trailer such as
+`Recx-Checked: lib, cli`; the reminder then disregards that commit's changes to those modules
+and the changes of the session's commits it descends from. `RECX_DRIFT_REMINDER=off` turns
+the reminder off. The [manifest skill](plugin/skills/manifest/SKILL.md) describes both in full.
+
 ## Searching
 
 ```sh
@@ -95,8 +103,9 @@ Every result is written by the repository's author and has been checked only aga
 schema. The output says so in a fixed `notice`, and the JSON lists the author-written paths in
 `untrusted`. The index never contains a manifest's `setup` or `run` commands. Before reusing
 anything, read the repository's licence file and its current `RECX.yaml`, and run its evidence
-only in a sandbox. [docs/design/search.md](docs/design/search.md) describes the index, the
-crawler and the ranking in full.
+only in a sandbox. [docs/integrating.md](docs/integrating.md) explains how to call search from
+another tool, and [docs/design/search.md](docs/design/search.md) describes the index, the crawler
+and the ranking in full.
 
 ## What's here
 

{recx_cli-0.1.0 → recx_cli-0.1.1}/README.md

@@ -61,6 +61,14 @@ anything listed can be reused without asking.
 
 Then add the GitHub topic `recx` to the repository, so the daily index finds it promptly.
 
+The plugin's hook runs when a session or one of its subagents stops (Claude Code's Stop and
+SubagentStop events). It blocks on an invalid manifest, and it reminds, without blocking, when
+files under a module's `path` changed during the session while RECX.yaml did not. A commit can
+record that module entries were checked against its tree with a trailer such as
+`Recx-Checked: lib, cli`; the reminder then disregards that commit's changes to those modules
+and the changes of the session's commits it descends from. `RECX_DRIFT_REMINDER=off` turns
+the reminder off. The [manifest skill](plugin/skills/manifest/SKILL.md) describes both in full.
+
 ## Searching
 
 ```sh
@@ -81,8 +89,9 @@ Every result is written by the repository's author and has been checked only aga
 schema. The output says so in a fixed `notice`, and the JSON lists the author-written paths in
 `untrusted`. The index never contains a manifest's `setup` or `run` commands. Before reusing
 anything, read the repository's licence file and its current `RECX.yaml`, and run its evidence
-only in a sandbox. [docs/design/search.md](docs/design/search.md) describes the index, the
-crawler and the ranking in full.
+only in a sandbox. [docs/integrating.md](docs/integrating.md) explains how to call search from
+another tool, and [docs/design/search.md](docs/design/search.md) describes the index, the crawler
+and the ranking in full.
 
 ## What's here
 

{recx_cli-0.1.0 → recx_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "recx-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Validator for RECX.yaml manifests: the recx check command."
 readme = "README.md"
 requires-python = ">=3.10"

{recx_cli-0.1.0 → recx_cli-0.1.1}/src/recx_cli/cli.py

@@ -168,8 +168,8 @@ def build_parser() -> argparse.ArgumentParser:
     hook_sub = hook.add_subparsers(dest="hook_command", required=True, parser_class=_Parser)
     hook_sub.add_parser(
         "stop",
-        help="Stop hook: keep the repository's RECX.yaml valid as a session ends",
-        description="Read Claude Code's Stop hook JSON on stdin. Always exits 0. "
+        help="Stop and SubagentStop hook: keep the repository's RECX.yaml valid",
+        description="Read Claude Code's Stop or SubagentStop hook JSON on stdin. Always exits 0. "
         "RECX_STOP_HOOK=block (default) blocks the stop while RECX.yaml is invalid, "
         "warn only gives feedback, off does nothing.",
     )

recx_cli-0.1.1/src/recx_cli/drift.py

@@ -0,0 +1,312 @@
+"""Drift reminder: a manifest can be valid and stale.
+
+`recx hook session-start` records the repository's HEAD for the session.
+`recx hook stop` (run on Stop and on SubagentStop) then asks which modules have
+changed files since, and, when RECX.yaml is not among them, reminds once per set
+of modules. A commit whose message carries the trailer
+`Recx-Checked: <module-id>[, <module-id>...]` records that those modules' entries
+were checked against the tree at that commit, so its changes to them, and those
+of its ancestors in the session's range, do not count. The reminder is only ever
+feedback, never a block. Callers swallow every exception raised here.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+from recx_cli.check import parse
+
+MANIFEST = "RECX.yaml"
+SKILL = "recx:manifest"
+_HEAD = re.compile(r"[0-9a-fA-F]{7,64}")
+_SAFE_ID = re.compile(r"[A-Za-z0-9_-]{1,128}")
+
+
+def enabled() -> bool:
+    return os.environ.get("RECX_DRIFT_REMINDER", "").strip().lower() != "off"
+
+
+def state_dir() -> Path:
+    plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA")
+    if plugin_data:
+        return Path(plugin_data)
+    base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state")
+    return Path(base) / "recx"
+
+
+def _state_file(session_id: str) -> Path | None:
+    if not isinstance(session_id, str) or not _SAFE_ID.fullmatch(session_id):
+        return None
+    return state_dir() / f"{session_id}.json"
+
+
+def read_state(session_id: str) -> dict:
+    """The session's state, or {} when absent, unreadable or corrupt."""
+    try:
+        path = _state_file(session_id)
+        if path is None:
+            return {}
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            return {}
+        state: dict = {}
+        head = data.get("head")
+        if isinstance(head, str) and _HEAD.fullmatch(head):
+            state["head"] = head
+        reminded = data.get("reminded")
+        if isinstance(reminded, list):
+            state["reminded"] = [m for m in reminded if isinstance(m, str)]
+        agents = data.get("agents")
+        if isinstance(agents, dict):
+            state["agents"] = {
+                a: [m for m in r if isinstance(m, str)]
+                for a, r in agents.items()
+                if isinstance(a, str) and _SAFE_ID.fullmatch(a) and isinstance(r, list)
+            }
+        return state
+    except Exception:  # noqa: BLE001 - a bad state file is ignored
+        return {}
+
+
+def write_state(session_id: str, state: dict) -> None:
+    path = _state_file(session_id)
+    if path is None:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".tmp-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(state, fh)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _git(top: Path, *args: str) -> str:
+    out = subprocess.run(
+        ["git", "-C", str(top), *args], capture_output=True, text=True, timeout=20, check=True
+    )
+    return out.stdout
+
+
+def head_of(top: Path) -> str | None:
+    value = _git(top, "rev-parse", "HEAD").strip()
+    return value if _HEAD.fullmatch(value) else None
+
+
+STATE_MAX_AGE_DAYS = 30
+
+
+def prune_state(max_age_days: int = STATE_MAX_AGE_DAYS) -> None:
+    """Delete session state files older than max_age_days; one is written per session."""
+    try:
+        cutoff = time.time() - max_age_days * 86400
+        for path in state_dir().glob("*.json"):
+            try:
+                if path.stat().st_mtime < cutoff:
+                    path.unlink()
+            except OSError:
+                continue
+    except OSError:
+        pass
+
+
+def session_start(session_id: str, top: Path) -> None:
+    """Record HEAD for the session. Skips when there is no manifest or the reminder is off."""
+    if not enabled() or not (top / MANIFEST).is_file():
+        return
+    prune_state()
+    head = head_of(top)
+    if head:
+        write_state(session_id, {"head": head, "reminded": []})
+
+
+_TRAILER_LINE = re.compile(r"\s*recx-checked\s*:(.*)", re.IGNORECASE)
+_ID_SEP = re.compile(r"[,\s]+")
+
+
+def _uncommitted(top: Path) -> set[str]:
+    """Files changed against HEAD in the index or working tree, plus untracked files."""
+    files = set(_git(top, "diff", "--name-only", "-z", "HEAD", "--").split("\0"))
+    files.update(_git(top, "ls-files", "--others", "--exclude-standard", "-z").split("\0"))
+    files.discard("")
+    return files
+
+
+def changed_files(top: Path, head: str | None) -> set[str]:
+    """The net change since head (or HEAD) plus untracked files: the reading without trailers."""
+    files: set[str] = set()
+    for base in [head, "HEAD"] if head else ["HEAD"]:
+        try:
+            files.update(_git(top, "diff", "--name-only", "-z", base, "--").split("\0"))
+            break
+        except (OSError, subprocess.SubprocessError):
+            continue
+    files.update(_git(top, "ls-files", "--others", "--exclude-standard", "-z").split("\0"))
+    files.discard("")
+    return files
+
+
+def checked_ids(trailers: str) -> set[str]:
+    """Module ids named by Recx-Checked trailers; anything malformed names nothing."""
+    ids: set[str] = set()
+    for line in trailers.splitlines():
+        m = _TRAILER_LINE.fullmatch(line)
+        if m:
+            ids.update(i for i in _ID_SEP.split(m.group(1)) if i)
+    return ids
+
+
+class Commit:
+    __slots__ = ("sha", "parents", "checked", "files")
+
+    def __init__(self, sha: str, parents: list[str], checked: set[str], files: set[str]) -> None:
+        self.sha, self.parents, self.checked, self.files = sha, parents, checked, files
+
+
+def range_commits(top: Path, head: str) -> list[Commit]:
+    """Every commit in head..HEAD with its parents, Recx-Checked ids and touched files.
+
+    Two `git log` calls: one for the graph and the files, which holds no free text,
+    and one for the trailers, NUL-separated, since a commit message cannot hold a
+    NUL. Merge commits list no files of their own; the commits they bring in are in
+    the range themselves. Raises when git fails (unknown head, shallow history, no
+    git); a record that does not parse is skipped.
+    """
+    rng = f"{head}..HEAD"
+    graph = _git(
+        top, "log", "-z", "--no-renames", "--no-ext-diff", "--format=%x1e%H %P%x1f", "--name-only", rng, "--"
+    )
+    trailers = _git(top, "log", "-z", "--format=%H%n%(trailers:only,unfold)", rng, "--")
+    checked: dict[str, set[str]] = {}
+    for record in trailers.split("\0"):
+        sha, _, text = record.partition("\n")
+        if _HEAD.fullmatch(sha):
+            checked[sha] = checked_ids(text)
+    commits: list[Commit] = []
+    for record in graph.split("\x1e"):
+        header, sep, rest = record.partition("\x1f")
+        shas = header.split()
+        if not sep or not shas or not all(_HEAD.fullmatch(x) for x in shas):
+            continue
+        rest = rest.lstrip("\0")
+        if rest.startswith("\n"):
+            rest = rest[1:]
+        files = {f for f in rest.split("\0") if f}
+        commits.append(Commit(shas[0], shas[1:], checked.get(shas[0], set()), files))
+    return commits
+
+
+def _covered(commits: list[Commit], module_id: str) -> set[str]:
+    """Commits in the range that a Recx-Checked trailer naming module_id vouches for.
+
+    A check vouches for the tree it was made on, so a checking commit covers itself
+    and every ancestor of it within the range. Every path from a commit in the range
+    to an ancestor in the range stays inside the range, so walking parents that are
+    in the range finds exactly those ancestors.
+    """
+    by_sha = {c.sha: c for c in commits}
+    covered: set[str] = set()
+    stack = [c.sha for c in commits if module_id in c.checked]
+    while stack:
+        sha = stack.pop()
+        if sha in covered:
+            continue
+        covered.add(sha)
+        stack.extend(p for p in by_sha[sha].parents if p in by_sha and p not in covered)
+    return covered
+
+
+def _modules(manifest: Path) -> list[tuple[str, str]]:
+    data = parse(manifest.read_text(encoding="utf-8"))
+    modules = data.get("modules") if isinstance(data, dict) else None
+    found: list[tuple[str, str]] = []
+    for mod in modules if isinstance(modules, list) else []:
+        if not isinstance(mod, dict):
+            continue
+        mid, path = mod.get("id"), mod.get("path")
+        if isinstance(mid, str) and isinstance(path, str):
+            found.append((mid, path))
+    return found
+
+
+def _touches(path: str, files: set[str]) -> bool:
+    if path.endswith("/"):
+        return any(f.startswith(path) for f in files)
+    return path in files
+
+
+def affected_modules(manifest: Path, files: set[str], commits: list[Commit] | None = None) -> list[str]:
+    """Modules whose path is touched by files, or by a commit no trailer for them covers."""
+    found: list[str] = []
+    for mid, path in _modules(manifest):
+        if mid in found:
+            continue
+        hit = _touches(path, files)
+        if not hit and commits:
+            covered = _covered(commits, mid)
+            hit = any(c.sha not in covered and _touches(path, c.files) for c in commits)
+        if hit:
+            found.append(mid)
+    return found
+
+
+def _changes(top: Path, head: str | None) -> tuple[set[str], list[Commit] | None]:
+    """(files changed outside any commit's trailer, the session's commits).
+
+    With a recorded head whose range git can read, the files are the uncommitted
+    and untracked ones and the commits are read one by one. Otherwise (no head,
+    or any failure reading the range) this is the reading without trailers: the
+    net change since head, or the uncommitted change alone, with no commits.
+    """
+    if head:
+        try:
+            return _uncommitted(top), range_commits(top, head)
+        except Exception:  # noqa: BLE001 - reading commits or trailers never costs the reminder
+            pass
+    return changed_files(top, head), None
+
+
+def reminder(session_id: str | None, top: Path, agent_id: str | None = None) -> str | None:
+    """The reminder text to emit now, or None. Records what it reminded about.
+
+    The session and each subagent (by agent_id) keep their own record of what they
+    were reminded about, so a subagent that is reminded never silences the session.
+    """
+    if not enabled():
+        return None
+    state = read_state(session_id) if session_id else {}
+    files, commits = _changes(top, state.get("head"))
+    if MANIFEST in files or any(MANIFEST in c.files for c in commits or []):
+        return None
+    affected = affected_modules(top / MANIFEST, files, commits)
+    if agent_id is not None and not _SAFE_ID.fullmatch(agent_id):
+        agent_id = None
+    agents = state.get("agents", {})
+    already = set(agents.get(agent_id, []) if agent_id else state.get("reminded", []))
+    if not affected or set(affected) <= already:
+        return None
+    if session_id:
+        seen = sorted(already | set(affected))
+        update = {"agents": {**agents, agent_id: seen}} if agent_id else {"reminded": seen}
+        try:
+            write_state(session_id, {**state, **update})
+        except Exception:  # noqa: BLE001 - failing to record must not lose the reminder
+            pass
+    names = ", ".join(affected)
+    return (
+        f"Reminder, not an error: files under these {MANIFEST} modules changed this session "
+        f"while {MANIFEST} did not: {names}. Check whether the manifest still describes them, "
+        f"using the {SKILL} skill, and update it if it does not. If it is still accurate, "
+        f"nothing needs doing."
+    )

{recx_cli-0.1.0 → recx_cli-0.1.1}/src/recx_cli/hook.py

@@ -1,8 +1,9 @@
-"""`recx hook stop`: Claude Code's Stop hook, keeping a RECX.yaml valid as a session ends.
+"""`recx hook stop`: Claude Code's Stop and SubagentStop hook, keeping a RECX.yaml valid.
 
-The hook must never trap a session on its own failure, so every error path
-exits 0 without output. Only an invalid manifest produces output, and it is
-always JSON on stdout with exit status 0.
+The same entry point serves both events; the event's own `hook_event_name` is
+named back in any `hookSpecificOutput`. The hook must never trap a session on
+its own failure, so every error path exits 0 without output. Output is always
+JSON on stdout with exit status 0.
 """
 
 from __future__ import annotations
@@ -18,6 +19,7 @@ from recx_cli.check import Unreadable, check_file, format_problem
 
 MANIFEST = "RECX.yaml"
 SKILL = "recx:manifest"
+EVENTS = ("Stop", "SubagentStop")
 
 
 def _mode() -> str:
@@ -55,6 +57,27 @@ def _read_event() -> tuple[dict, Path] | None:
     return event, _manifest_dir(cwd)
 
 
+def _event_name(event: dict) -> str:
+    name = event.get("hook_event_name")
+    return name if name in EVENTS else "Stop"
+
+
+def _internal_agent(event: dict) -> bool:
+    """A SubagentStop from one of Claude Code's own agents (prompt suggestions, /btw).
+
+    Claude Code documents an empty `agent_type` for those when the session runs
+    without --agent. Such an agent did not do the session's work and cannot act on
+    feedback, so neither the check nor the reminder is spent on it.
+    """
+    return _event_name(event) == "SubagentStop" and not event.get("agent_type")
+
+
+def _context(event: dict, text: str) -> str:
+    return json.dumps(
+        {"hookSpecificOutput": {"hookEventName": _event_name(event), "additionalContext": text}}
+    )
+
+
 def _validity(event: dict, top: Path) -> tuple[bool, str | None]:
     """(manifest is valid, output to print). Knows nothing about drift."""
     manifest = top / MANIFEST
@@ -75,20 +98,23 @@ def _validity(event: dict, top: Path) -> tuple[bool, str | None]:
         return False, json.dumps({"decision": "block", "reason": reason})
     still = " still" if event.get("stop_hook_active") is True else ""
     context = f"{MANIFEST} is{still} invalid. The {SKILL} skill explains how to fix it:\n{lines}"
-    return False, json.dumps(
-        {"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": context}}
-    )
+    return False, _context(event, context)
 
 
 def _drift(event: dict, top: Path) -> str | None:
     try:
         session = event.get("session_id")
-        text = drift.reminder(session if isinstance(session, str) else None, top)
+        agent = event.get("agent_id") if _event_name(event) == "SubagentStop" else None
+        text = drift.reminder(
+            session if isinstance(session, str) else None,
+            top,
+            agent if isinstance(agent, str) else None,
+        )
     except BaseException:  # noqa: BLE001 - the drift path must never block or raise
         return None
     if text is None:
         return None
-    return json.dumps({"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": text}})
+    return _context(event, text)
 
 
 def _run() -> None:
@@ -98,6 +124,8 @@ def _run() -> None:
     if parsed is None:
         return
     event, top = parsed
+    if _internal_agent(event):
+        return
     valid, output = _validity(event, top)
     if output is not None:
         print(output)