@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/hooks/_updatelib.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+# codeArbiter — update-available notifier: shared cache/compare/fetch logic.
+#
+# codeArbiter ships via a third-party marketplace, which Claude Code does NOT
+# auto-update by default (only official Anthropic marketplaces get that). This
+# module backs a lightweight notifier so a stale install is surfaced instead of
+# running forever unnoticed: it reads the installed plugin.json version, reads
+# a small user-global cache of the latest published GitHub release, and — when
+# the cache says a newer version exists — hands back a single notice line. Both
+# SessionStart and the statusline render from that SAME cache; neither makes a
+# network call on its own hot path (issue #194's constraint).
+#
+# The only network call this module makes (fetch_latest_tag) is invoked from
+# the OFF-hot-path detached refresh (see hooks/update-refresh.py, spawned by
+# session-start.py). refresh_if_stale() gates that call to at most once per
+# day via the cached `checked_at`, and is fail-silent end to end: any network
+# error, timeout, non-200, or unparseable body degrades to "keep the last-known
+# latest" — never a traceback, never a crash of the host hook.
+#
+# Design principles (mirroring _ledgerlib.py / _taskboardlib.py):
+#   - Stdlib only (urllib, json) — no third-party dependency, ever (ADR-0004).
+#   - HTTPS-only fetch target (ADR-0003); a non-https url is refused outright.
+#   - Zero side effects at import time — no network, no file I/O on import.
+#   - Never raise on malformed/absent input — degrade to "no notice".
+#
+# Public API:
+#   ONE_DAY                                  once-daily refresh interval (seconds)
+#   UPDATE_API_URL                           GitHub Releases API endpoint (module constant)
+#   state_path() -> str                      resolved cache file path (env-overridable)
+#   plugin_root(explicit=None) -> str        the running plugin's own root directory
+#   installed_version(root=None, host=None) -> str|None  the version in
+#                                             <root>/<host.manifest_relpath()>
+#                                             (host defaults to _hooklib.get_host())
+#   parse_version(s) -> tuple|None           numeric-tuple parse; None if malformed/absent
+#   version_gt(a, b) -> bool                 True iff semver a > b (numeric-tuple compare)
+#   update_available(installed, latest) -> bool   True iff latest > installed
+#   notice_line(installed, latest) -> str|None    the SessionStart/statusline notice text
+#   read_state(path=None) -> dict            {latest, checked_at} cache, or {} on any failure
+#   write_state(state, path=None) -> None    atomic cache write; best-effort, never raises
+#   is_stale(checked_at, now, interval=ONE_DAY) -> bool   True iff a refresh is due
+#   fetch_latest_tag(url=UPDATE_API_URL, timeout=3.0, opener=None) -> str|None   HTTPS GET, fail-silent
+#   refresh_if_stale(now=None, fetcher=None, path=None) -> dict   best-effort cache refresh
+
+import json
+import os
+import re
+import sys
+import time
+import urllib.request
+
+# Reuse the ONE atomic-write helper defined in _hooklib.py (same rationale as
+# _previewlib.py: _hooklib sits beside this file; mount its dir on sys.path the
+# same way the test harness does before importing by reference).
+_HOOKS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _HOOKS_DIR not in sys.path:
+    sys.path.insert(0, _HOOKS_DIR)
+from _hooklib import get_host, write_text_atomic  # noqa: E402 — sys.path mount above
+# hostapi is not imported directly here (#257): plugin_root()/installed_version()
+# resolve the Host via _hooklib.get_host() (the DI seam every entry script's
+# run(host) primes via set_host()), never a fresh hostapi.load_host().
+
+ONE_DAY = 24 * 60 * 60
+
+# The repo's own GitHub Releases API — unauthenticated GET, HTTPS only (ADR-0003).
+# The release tag equals plugin.json's version (an established repo invariant).
+UPDATE_API_URL = "https://api.github.com/repos/arbiterForge/codeArbiter/releases/latest"
+
+_VERSION_STRIP_RE = re.compile(r"^[vV]")
+
+
+def state_path():
+    """Resolved cache file path. User-GLOBAL (~/.codearbiter/...), not project-scoped
+    — the notice concerns the plugin's own version, not any one project. Env-overridable
+    (CODEARBITER_UPDATE_STATE) for tests, mirroring _ledgerlib.ledger_path()."""
+    return os.environ.get("CODEARBITER_UPDATE_STATE") or \
+        os.path.join(os.path.expanduser("~"), ".codearbiter", "update-state.json")
+
+
+def plugin_root(explicit=None):
+    """The running plugin's own root directory (parent of hooks/). `explicit` wins
+    (tests); else CLAUDE_PLUGIN_ROOT; else derived from this file's own location —
+    always resolves to the ACTUAL running install, not a stale env pin. The env
+    + file-relative resolution lives on the host seam (hostapi, ADR-0011).
+    Resolves via get_host() (#257), not a direct hostapi.load_host(), so a
+    caller reached from an entry script's run(host) sees the SAME injected
+    Host instead of triggering a second disk load."""
+    return explicit or get_host().plugin_root()
+
+
+def installed_version(root=None, host=None):
+    """The `version` field from <root>/<host.manifest_relpath()>, or None on any
+    failure (missing file, corrupt JSON, missing/blank field). `host` defaults to
+    get_host() (#263, reliability-002/observability-003; #257 — get_host(), not
+    a direct hostapi.load_host(), so this resolves the SAME injected instance):
+    under Claude Code that resolves to `.claude-plugin/plugin.json` exactly as
+    before; a plugin whose manifest ships elsewhere (e.g. ca-codex's
+    `.codex-plugin/`) resolves the CORRECT path instead of silently reading
+    nothing and suppressing the update-available notice forever. No caller in
+    this repo threads a host through today (session-start.py calls
+    installed_version(plugin) positionally), so resolving it here — rather
+    than plumbing it through every call site — keeps the fix local to this
+    seam."""
+    root = root or plugin_root()
+    host = host or get_host()
+    try:
+        with open(os.path.join(root, host.manifest_relpath()),
+                  encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None
+    v = data.get("version") if isinstance(data, dict) else None
+    return v if isinstance(v, str) and v.strip() else None
+
+
+def parse_version(s):
+    """Parse a version string into a numeric tuple, e.g. "v2.10.0+build.5" -> (2, 10, 0).
+    A leading 'v', build metadata (+...), and a prerelease suffix (-...) are tolerated
+    and stripped. Returns None for anything that isn't a dotted run of digits (AC-6:
+    malformed/absent -> None, so the caller yields no notice)."""
+    if not isinstance(s, str):
+        return None
+    s = _VERSION_STRIP_RE.sub("", s.strip())
+    s = s.split("+", 1)[0]
+    s = s.split("-", 1)[0]
+    if not s:
+        return None
+    parts = s.split(".")
+    if not parts or not all(p.isdigit() for p in parts):
+        return None
+    return tuple(int(p) for p in parts)
+
+
+def version_gt(a, b):
+    """True iff semver `a` > `b`, numeric-tuple compared (2.10.0 > 2.9.0, never a
+    lexicographic string compare). Either side malformed/absent -> False (AC-6)."""
+    ta, tb = parse_version(a), parse_version(b)
+    if ta is None or tb is None:
+        return False
+    n = max(len(ta), len(tb))
+    ta = ta + (0,) * (n - len(ta))
+    tb = tb + (0,) * (n - len(tb))
+    return ta > tb
+
+
+def update_available(installed, latest):
+    """True iff `latest` is a well-formed version strictly greater than `installed`."""
+    return version_gt(latest, installed)
+
+
+def notice_line(installed, latest):
+    """The single-line SessionStart/statusline notice, or None when no update is due
+    (AC-1/AC-2): `codeArbiter: update available X -> Y (run /plugin marketplace update
+    codearbiter)`. Never multi-line; never emitted for equal, lesser, missing, or
+    malformed `latest`."""
+    if not update_available(installed, latest):
+        return None
+    return (f"codeArbiter: update available {installed} -> {latest} "
+            f"(run /plugin marketplace update codearbiter)")
+
+
+def read_state(path=None):
+    """The cached `{latest, checked_at}` state, or {} on ANY failure (missing file,
+    corrupt JSON, non-dict content) — a corrupt cache degrades to 'no notice', never
+    a crash of the host hook."""
+    path = path or state_path()
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def write_state(state, path=None):
+    """Atomically persist `state` to the cache file, creating parent dirs as needed.
+    Best-effort: ANY failure (permissions, missing/blocked parent) is swallowed — a
+    cache write must never crash the caller (the detached refresh, or a test)."""
+    path = path or state_path()
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        write_text_atomic(path, json.dumps(state), newline="\n")
+    except Exception:  # noqa: BLE001 — best-effort cache write, never raise
+        pass
+
+
+def is_stale(checked_at, now, interval=ONE_DAY):
+    """True iff a refresh is due: no prior check, or `interval` seconds have elapsed
+    since `checked_at`. A malformed `checked_at` is treated as stale (never crashes,
+    never wedges the gate closed)."""
+    if checked_at is None:
+        return True
+    try:
+        return (now - float(checked_at)) >= interval
+    except (TypeError, ValueError):
+        return True
+
+
+class _HTTPSOnlyRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Refuse to follow any redirect whose target isn't `https://` (ADR-0003,
+    defense-in-depth). The pre-connection scheme guard in fetch_latest_tag below
+    only covers the INITIAL url — urllib's default opener otherwise follows a
+    3xx transparently, including an https->http downgrade, without ever
+    re-checking the scheme. Returning None here means the redirect is NOT
+    handled, so urllib's error chain raises the original HTTPError instead of
+    silently continuing the chain over a downgraded (or otherwise non-https)
+    target; fetch_latest_tag's broad except then degrades that to None, same as
+    every other fetch failure (fail-silent, AC-5)."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if not (isinstance(newurl, str) and newurl.lower().startswith("https://")):
+            return None
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _build_opener():
+    """Factory for the HTTPS-only-redirect opener. A thin seam — not called
+    directly by fetch_latest_tag's default path only, but exposed as a factory
+    (rather than a module-level singleton) so `opener=` injection in tests never
+    has to touch real urllib internals."""
+    return urllib.request.build_opener(_HTTPSOnlyRedirectHandler())
+
+
+def fetch_latest_tag(url=UPDATE_API_URL, timeout=3.0, opener=None):
+    """GET the GitHub Releases API and return `tag_name`, or None on ANY problem
+    (AC-5): non-https url, network error, timeout, non-200, an unparseable/absent
+    body, or a redirect to a non-https target. HTTPS-only per ADR-0003 — a
+    non-https INITIAL url is refused before any connection is attempted, and a
+    non-https REDIRECT target is refused too (via `_HTTPSOnlyRedirectHandler`,
+    since urllib's default opener would otherwise follow an https->http
+    downgrade transparently). `opener` is injectable (tests); production builds
+    the hardened opener via `_build_opener()`."""
+    if not isinstance(url, str) or not url.lower().startswith("https://"):
+        return None
+    try:
+        req = urllib.request.Request(url, headers={
+            "User-Agent": "codeArbiter-update-check",
+            "Accept": "application/vnd.github+json",
+        })
+        op = opener or _build_opener()
+        with op.open(req, timeout=timeout) as resp:
+            status = getattr(resp, "status", None) or getattr(resp, "code", None)
+            if status != 200:
+                return None
+            body = resp.read()
+        data = json.loads(body.decode("utf-8", "replace"))
+        tag = data.get("tag_name") if isinstance(data, dict) else None
+        return tag.strip() if isinstance(tag, str) and tag.strip() else None
+    except Exception:  # noqa: BLE001 — AC-5: fail-silent on any network/parse error
+        return None
+
+
+def refresh_if_stale(now=None, fetcher=None, path=None):
+    """Best-effort, once-daily, fail-silent cache refresh (AC-3/AC-4/AC-5).
+
+    Reads the cache; if `checked_at` is still fresh (is_stale() False), returns it
+    UNCHANGED and calls the fetcher NOT AT ALL (AC-4 — at most one fetch per day).
+    Otherwise calls `fetcher()` (default fetch_latest_tag): on success the new
+    `latest` is cached; on ANY exception or a None/falsy return, the PRIOR `latest`
+    is preserved (fail-silent — a network hiccup never blanks a known-good notice)
+    and `checked_at` still advances, so a persistently-unreachable network is not
+    retried every single session that day. Never raises (AC-3)."""
+    now = time.time() if now is None else now
+    path = path or state_path()
+    state = read_state(path)
+    checked_at = state.get("checked_at") if isinstance(state, dict) else None
+    if not is_stale(checked_at, now):
+        return state
+    fetch = fetcher or fetch_latest_tag
+    try:
+        latest = fetch()
+    except Exception:  # noqa: BLE001 — AC-3/AC-5: never propagate a fetch failure
+        latest = None
+    new_state = {
+        "latest": latest if latest else state.get("latest"),
+        "checked_at": now,
+    }
+    write_state(new_state, path)
+    return new_state

package/plugins/ca-pi/hooks/babysit.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+# codeArbiter — thin entry point for the pr-babysitter config resolver
+# (architecture-006/#179).
+#
+# Wraps _babysitlib.main (the CLI shim over babysit_config) so /ca:pr and
+# /ca:watch invoke a thin, non-underscore entry hook instead of running the
+# underscore library itself as a script. Mirrors doctor.py / taskwrite.py:
+# entry point stays thin, all resolution logic lives in _babysitlib.
+#
+# Invoked by command prose as (interpreter resolved once by presence, never a
+# `python3 X || python X` fold -- #577):
+#   "$PY" "<plugin>/hooks/babysit.py" --root "<dir>"
+#
+# Prints one JSON line, e.g. {"enabled": true, "on_red": "propose"}. Fail-safe:
+# _babysitlib.main() itself never raises past its own try/except (any resolver
+# error degrades to the OFF default) — this wrapper adds no additional risk.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _hooklib  # noqa: E402 — set_host DI seam (#257)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+import _babysitlib  # noqa: E402
+
+
+def main(argv=None):
+    return _babysitlib.main(argv)
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Delegates to main(argv) and returns its exit code,
+    exactly as the old `sys.exit(main())` guard propagated it.
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so any `get_host()` call downstream
+    resolves to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, _hooklib.set_host,
+                               pass_argv=True, propagate_result=True)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

package/plugins/ca-pi/hooks/boardsync.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+# codeArbiter — board-drift reconcile entrypoint (advisory, read-only sweep).
+#
+# Surfaces drift between task-board state and merged-commit references.
+# Writes nothing — open-tasks.md is never opened for writing by this module.
+#
+# Design invariants:
+#   - reconcile_report(board_text, log_text, today) -> str is pure; never raises.
+#   - main(argv) is the thin I/O shell: reads board read-only via read_board(),
+#     reads merged-commit text from stdin (the caller pipes `git log` output — no
+#     subprocess in this module, mirroring how _standuplib stays subprocess-free),
+#     then calls reconcile_report and prints the result.
+#   - Stdlib only. No subprocess calls. No write paths of any kind.
+#
+# Public API:
+#   reconcile_report(board_text, log_text, today) -> str
+#   main(argv=None)
+
+import argparse
+import datetime
+import os
+import sys
+
+# Handles both "run as script" and "imported from the tests/ sub-dir": ensures
+# the hooks package directory is on sys.path so _taskboardlib resolves cleanly
+# regardless of cwd or how Python was invoked.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _hooklib  # noqa: E402 — set_host DI seam (#257)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+import _taskboardlib as tb  # noqa: E402
+
+
+def reconcile_report(board_text, log_text, today):
+    """Return a human-readable advisory drift report string.
+
+    Calls extract_task_ids(log_text), then find_board_drift against board_text,
+    and formats the result: drifted tasks (id + state) and unknown ids, or a
+    clean 'no drift detected' line when nothing needs attention.
+
+    Pure — never raises. None/empty inputs degrade to a clean (empty) report.
+
+    Drifted = task whose board state is not [x] but whose id appeared in the
+    merged-commit log (work landed, board not flipped). Unknown = id in the log
+    absent from the board entirely (informational only; never treated as drift).
+    """
+    try:
+        merged_ids = tb.extract_task_ids(log_text or "")
+        result = tb.find_board_drift(board_text or "", merged_ids, today)
+        lines = [f"Board drift sweep — {result.observed.isoformat()}"]
+        if not result.drifted and not result.unknown:
+            lines.append("  no drift detected")
+        else:
+            if result.drifted:
+                lines.append("  DRIFTED (merged but not [x]):")
+                for t in result.drifted:
+                    lines.append(f"    {t.id}  state={t.state}")
+            if result.unknown:
+                lines.append("  UNKNOWN ids (in log but not on board):")
+                for uid in result.unknown:
+                    lines.append(f"    {uid}")
+        return "\n".join(lines)
+    except Exception:  # noqa: BLE001
+        return "Board drift sweep — error during report (input may be malformed)"
+
+
+def main(argv=None):
+    """Thin I/O entrypoint for the board-drift advisory sweep.
+
+    Reads the board file read-only via _taskboardlib.read_board (never opens it
+    for writing). Reads merged-commit text from stdin. Prints the advisory report
+    produced by reconcile_report. Writes nothing.
+
+    Subcommands:
+      reconcile [--board PATH]   surface drift; board is never written.
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="boardsync",
+        description="Advisory board-drift sweep — never writes open-tasks.md.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    rec = sub.add_parser("reconcile", help="surface board drift (read-only)")
+    rec.add_argument(
+        "--board",
+        default=".codearbiter/open-tasks.md",
+        metavar="PATH",
+        help="path to open-tasks.md (default: .codearbiter/open-tasks.md)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "reconcile":
+        # Defense-in-depth: honor the module's crash-safe invariant for the I/O
+        # path too (read_board / stdin), not just reconcile_report — a malformed
+        # --board or a stdin read error degrades to the advisory report, never a
+        # traceback. (Security review 2026-06-26, LOW.)
+        today = datetime.date.today()
+        try:
+            board_text = tb.read_board(args.board)
+            log_text = sys.stdin.read()
+            report = reconcile_report(board_text or "", log_text, today)
+        except Exception:
+            report = reconcile_report("", "", today)
+        print(report)
+    else:
+        parser.print_help()
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main(argv) unchanged — main()'s return value
+    stays discarded exactly as the old bare `main()` guard discarded it (so
+    the process still exits 0 on a normal fall-through).
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so any `get_host()` call downstream
+    resolves to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, _hooklib.set_host,
+                               pass_argv=True, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)