claude-smart 0.2.29 → 0.2.31

package/plugin/src/claude_smart/hook_log.py

@@ -0,0 +1,301 @@
+"""Structured, append-only log of every hook fire and its outcome.
+
+Why a dedicated log rather than relying on the Python ``logging`` module:
+hooks run as short-lived subprocesses with no preconfigured handler, so
+``_LOGGER.warning(...)`` calls silently vanish to stderr that Claude Code
+captures but typically does not surface. The dispatcher already wraps
+handlers in a broad ``except`` (so a hook crash never breaks the user's
+session) — without a forensic trail the silent-fail mode is invisible.
+
+This module writes one JSON line per hook fire to
+``~/.claude-smart/hook.log`` from ``hook.main`` after the handler returns.
+The Stop and SessionEnd handlers additionally piggyback their publish
+outcome into the record so the chain hook→adapter→backend is fully
+observable from a single file.
+
+Failure policy: every public function in this module swallows all
+``OSError``/``Exception`` paths. Logging is best-effort; a stuck disk
+or read-only ``$HOME`` must never abort an in-progress hook.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import time
+from collections.abc import Iterator
+from pathlib import Path
+from typing import IO, Any
+
+# ``fcntl`` is POSIX-only. On Windows we skip the cross-process lock and
+# accept the unlikely rotation race (claude-smart is primarily a POSIX
+# tool for Claude Code's plugin runtime).
+try:
+    import fcntl as _fcntl
+except ImportError:  # pragma: no cover — exercised on Windows only
+    _fcntl = None  # type: ignore[assignment]
+
+_LOGGER = logging.getLogger(__name__)
+
+# Anchored on $HOME so unit tests can monkeypatch ``_LOG_PATH`` to a
+# tmp_path. The directory is created lazily on first write — keeping
+# import side-effect-free matches the rest of the package.
+_LOG_PATH = Path.home() / ".claude-smart" / "hook.log"
+
+_TRUNCATE_LIMIT = 4096
+
+# Hard cap on ``hook.log`` size. At ~400 bytes/line and ~50 lines per
+# typical session, 5 MB ≈ 12k records ≈ a few hundred sessions of recent
+# forensic history — enough to debug the last week, bounded so a power
+# user's log can't grow unbounded.
+_MAX_LOG_BYTES = 5 * 1024 * 1024
+
+
+def log_event(
+    *,
+    event: str,
+    host: str,
+    session_id: Any = None,
+    project_id: Any = None,
+    cwd: Any = None,
+    internal_skipped: bool = False,
+    handler_status: str = "ok",
+    publish_status: str | None = None,
+    publish_count: int | None = None,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    """Append one JSON record describing a hook fire.
+
+    Args:
+        event (str): Hook event name (``"stop"``, ``"user-prompt"``, …).
+        host (str): Host identifier (``"claude-code"`` / ``"codex"``).
+        session_id (Any): Claude Code session id from the payload, or
+            ``None`` when the payload didn't carry one.
+        project_id (Any): Project-id resolved from ``cwd``. Optional.
+        cwd (Any): Working directory reported by the hook payload.
+            Optional — preserved verbatim so a future audit can correlate
+            fires against workspace directories.
+        internal_skipped (bool): True when ``is_internal_invocation``
+            short-circuited the dispatcher (reflexio-internal sub-claude
+            calls, or invocations from inside the reflexio submodule).
+        handler_status (str): ``"ok"`` for a clean return, ``"unknown_event"``
+            when no handler is registered, or ``"raised:<ExcClass>: <msg>"``
+            when the handler raised — formatted by ``hook.main``.
+        publish_status (str | None): Status returned by
+            ``publish.publish_unpublished`` (``"ok"`` / ``"failed"`` /
+            ``"nothing"``). Only emitted by Stop + SessionEnd.
+        publish_count (int | None): Interaction count from the same
+            tuple. ``None`` when the handler doesn't publish.
+        extra (dict[str, Any] | None): Free-form fields preserved as-is.
+
+    Returns:
+        None
+    """
+    record: dict[str, Any] = {
+        "ts": int(time.time()),
+        "event": event,
+        "host": host,
+        "session_id": _truncate(session_id),
+        "project_id": _truncate(project_id),
+        "cwd": _truncate(cwd),
+        "internal_skipped": bool(internal_skipped),
+        "handler_status": _truncate(handler_status),
+    }
+    if publish_status is not None:
+        record["publish_status"] = publish_status
+        try:
+            record["publish_count"] = int(
+                publish_count if publish_count is not None else 0
+            )
+        except (TypeError, ValueError):
+            # Defensive: a hostile caller passing an unparseable publish_count
+            # must not abort the hook fire. Treat as zero, the record still
+            # writes with publish_status preserved.
+            record["publish_count"] = 0
+    if extra:
+        for key, value in extra.items():
+            if key in record:
+                continue
+            record[key] = _truncate(value)
+
+    try:
+        line = json.dumps(record, ensure_ascii=False, default=str) + "\n"
+    except (TypeError, ValueError) as exc:
+        _LOGGER.debug("hook_log: json encode failed: %s", exc)
+        return
+
+    path = log_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: mkdir for %s failed: %s", path.parent, exc)
+        return
+
+    # Hold an exclusive cross-process flock through the entire append +
+    # rotate critical section. The original rationale ("POSIX atomic
+    # append below PIPE_BUF") protects the *append* alone but not the
+    # ``read_bytes → write tmp → rename`` rotation sequence: a concurrent
+    # appender that lands between rotation's read and rename has its
+    # record silently dropped by the rename. The lock closes that gap.
+    #
+    # On Windows ``_fcntl`` is None and writes proceed unlocked — same
+    # behaviour as before. The original PIPE_BUF-based append atomicity
+    # is preserved by ``_TRUNCATE_LIMIT`` keeping each record below 4 KiB.
+    with _rotation_lock(path):
+        try:
+            with path.open("a", encoding="utf-8") as fh:
+                fh.write(line)
+        except OSError as exc:
+            _LOGGER.debug("hook_log: write to %s failed: %s", path, exc)
+            return
+
+        # Rotate AFTER the append so the just-written record always survives,
+        # even on the call that crosses the cap. A single oversized record
+        # still gets through and is dropped by the *next* rotation when the
+        # file is read back.
+        _maybe_rotate(path)
+
+
+def log_path() -> Path:
+    """Return the active log path, honouring ``CLAUDE_SMART_HOOK_LOG``.
+
+    Resolution order:
+
+    1. ``CLAUDE_SMART_HOOK_LOG`` env var — escape hatch for tests and
+       advanced users who want the log elsewhere.
+    2. ``_LOG_PATH`` module attribute — what monkeypatched tests override.
+    3. ``~/.claude-smart/hook.log`` — the default.
+
+    Returns:
+        Path: The absolute path to write to.
+    """
+    override = os.environ.get("CLAUDE_SMART_HOOK_LOG")
+    if override:
+        return Path(override)
+    return _LOG_PATH
+
+
+def _truncate(value: Any) -> Any:
+    """Cap string values to ``_TRUNCATE_LIMIT`` chars so single-line writes
+    stay below the POSIX atomic-append limit.
+
+    Non-string values pass through unchanged; the json encoder handles
+    them. ``None`` becomes ``null`` in the JSON, which is what we want.
+    """
+    if isinstance(value, str) and len(value) > _TRUNCATE_LIMIT:
+        return value[:_TRUNCATE_LIMIT] + "…"
+    return value
+
+
+@contextlib.contextmanager
+def _rotation_lock(path: Path) -> Iterator[None]:
+    """Hold an exclusive cross-process flock on a sibling ``.lock`` file.
+
+    Serialises every ``log_event`` call against itself so the rotation
+    ``read_bytes → write tmp → rename`` sequence cannot interleave with a
+    concurrent append. On Windows or when the lock cannot be acquired
+    (no ``fcntl``, read-only parent, etc.) the lock degrades to a no-op
+    and the caller proceeds unlocked — matches the pre-existing
+    best-effort policy of this module.
+
+    Args:
+        path (Path): The log file path; the lock file is a sibling at
+            ``<path>.lock``.
+
+    Yields:
+        None.
+    """
+    if _fcntl is None:
+        yield
+        return
+    lock_path = path.with_name(path.name + ".lock")
+    fh: IO[bytes] | None = None
+    try:
+        fh = lock_path.open("ab")
+    except OSError as exc:
+        _LOGGER.debug("hook_log: lock open %s failed: %s", lock_path, exc)
+        yield
+        return
+    try:
+        _fcntl.flock(fh.fileno(), _fcntl.LOCK_EX)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: flock acquire failed: %s", exc)
+        fh.close()
+        yield
+        return
+    try:
+        yield
+    finally:
+        with contextlib.suppress(OSError):
+            _fcntl.flock(fh.fileno(), _fcntl.LOCK_UN)
+        with contextlib.suppress(OSError):
+            fh.close()
+
+
+def _maybe_rotate(path: Path) -> None:
+    """Cap ``path`` at ``_MAX_LOG_BYTES`` by dropping the oldest half in place.
+
+    The fast path is a single ``stat`` syscall — when the file is under
+    the cap (the overwhelmingly common case on every fire) we do nothing.
+    When over the cap we read the file, find the first newline at-or-after
+    the midpoint byte, and atomically replace the original with the bytes
+    *after* that newline. Splitting on a newline boundary preserves the
+    JSON Lines invariant: every retained line is a complete record.
+
+    We picked this over ``logging.handlers.RotatingFileHandler`` because:
+
+    1. ``hook_log`` deliberately avoids the ``logging`` framework — see
+       module docstring. Adding a handler reintroduces the configuration
+       fragility we were dodging.
+    2. ``RotatingFileHandler`` produces ``hook.log.1``, ``hook.log.2`` …
+       sidecar files; our forensic story is "one file, tail it". Users
+       have already wired up tooling around that path.
+    3. In-place truncate-to-second-half is O(n) on the rare rotation
+       event and zero-cost on every other write. Backup file management
+       would add steady-state inode pressure for no benefit.
+
+    Args:
+        path (Path): The log file to inspect. Need not exist — the
+            ``FileNotFoundError`` branch of the ``stat`` call returns
+            cleanly via the ``OSError`` guard.
+
+    Returns:
+        None
+    """
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        _LOGGER.debug("hook_log: stat for rotation failed: %s", exc)
+        return
+
+    if size < _MAX_LOG_BYTES:
+        return
+
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        _LOGGER.debug("hook_log: read for rotation failed: %s", exc)
+        return
+
+    midpoint = len(data) // 2
+    cut = data.find(b"\n", midpoint)
+    # ``find`` returns -1 when the second half has no newline at all,
+    # meaning the file is one giant record with no framing left to
+    # preserve. Drop the lot rather than split a record mid-byte.
+    tail = b"" if cut == -1 else data[cut + 1 :]
+
+    # Atomic replace: write to a sibling temp file then rename. This
+    # avoids the truncation window where a concurrent reader would see
+    # an empty file, and matches the contract that ``hook.log`` always
+    # contains complete JSONL framing.
+    tmp_path = path.with_name(path.name + ".rot")
+    try:
+        tmp_path.write_bytes(tail)
+        tmp_path.replace(path)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: rotation rename failed: %s", exc)
+        # Best-effort cleanup of the temp file; ignore failures.
+        with contextlib.suppress(OSError):
+            tmp_path.unlink(missing_ok=True)

package/plugin/uv.lock

@@ -419,7 +419,7 @@ wheels = [
 
 [[package]]
 name = "claude-smart"
-version = "0.2.29"
+version = "0.2.31"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },