cherry-docs 0.2.0__py3-none-any.whl

scripts/claude_hooks/state_manager.py

@@ -0,0 +1,526 @@
+#!/usr/bin/env python3
+"""Local session state manager for Claude Code hooks.
+
+Commands: session-start | post-tool-use | stop | reset
+State isolated per session_id; override path via CHERRY_HOOKS_STATE_FILE.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from app.services.capture_adapters import append_capture_event, infer_capture_event_type
+from app.services.capture_core import CaptureEventType
+
+_STATE_FILE_DEFAULT = Path(".claude/hooks/session_state.json")
+_HOME_CHERRY = Path.home() / ".cherrydocs"
+_CAPTURE_BUFFER_ROOT = Path(os.environ.get("CHERRY_CAPTURE_BUFFER_DIR", str(_HOME_CHERRY / "capture")))
+_PROMOTED_ROOT = Path(os.environ.get("CHERRY_PROMOTED_ROOT", str(_HOME_CHERRY / "promoted")))
+_SESSION_ID_FILE = _CAPTURE_BUFFER_ROOT / ".current-session-id"
+
+_DEFAULTS: dict = {
+    "session_initialized": False,
+    "needs_log": False,
+    "needs_checkpoint": False,
+    "last_log_at": None,
+    "last_checkpoint_at": None,
+    "meaningful_work_done": False,
+    "edits_since_last_log": 0,
+    "files_touched": [],
+}
+
+# Edit/write actions that produce durable code changes.
+_CODE_TOOLS = frozenset({"Edit", "Write", "NotebookEdit"})
+# Running commands — may produce findings worth logging (test results, errors).
+_RUN_TOOLS = frozenset({"Bash"})
+# CherryDocs tools that satisfy requirements.
+_LOG_TOOLS = frozenset({"mcp__cherry-docs__log_activity"})
+_CHECKPOINT_TOOLS = frozenset({"mcp__cherry-docs__save_checkpoint"})
+
+# After this many edits without a log, remind at every prompt.
+_LOG_NUDGE_AFTER_EDITS = 3
+
+_CLAUDE_PROMPT_PATH = Path(".claude/CLAUDE.md")
+_GENERATED_PROMPT_RE = re.compile(
+    r"Generated from docs/agent_protocol\.toml version=([^\s]+) hash=([0-9a-f]+);"
+)
+_GIT_COMMIT_OUTPUT_RE = re.compile(r"\[(?:[^\]]+)\s+([0-9a-f]{5,40})\]")
+
+_STARTUP_REMINDER = """\
+[CHERRYDOCS STARTUP]
+Protocol reminder for this session:
+  1. Call onboard to load the default project memory view.
+  2. Work normally and let passive capture record raw traces when available.
+  3. Use remember/log_activity only when something important would otherwise be lost.
+"""
+
+
+def _append_capture_event(
+    event_type: CaptureEventType,
+    *,
+    session_id: str | None,
+    cwd: str | None = None,
+    text: str | None = None,
+    command: str | None = None,
+    exit_code: int | None = None,
+    metadata: dict | None = None,
+) -> None:
+    try:
+        append_capture_event(
+            buffer_dir=_CAPTURE_BUFFER_ROOT,
+            source="claude-code",
+            event_type=event_type,
+            session_id=session_id,
+            cwd=cwd,
+            text=text,
+            command=command,
+            exit_code=exit_code,
+            metadata=metadata,
+        )
+    except Exception:
+        return
+
+
+def _parse_edited_file(event: dict) -> str | None:
+    """Extract the file path from an Edit/Write tool input."""
+    tool_input = event.get("tool_input") or {}
+    if isinstance(tool_input, str):
+        try:
+            tool_input = json.loads(tool_input)
+        except json.JSONDecodeError:
+            return None
+    return tool_input.get("file_path") or tool_input.get("path") or None
+
+
+def _parse_generated_prompt_metadata(text: str) -> dict | None:
+    m = _GENERATED_PROMPT_RE.search(text)
+    if not m:
+        return None
+    return {"version": m.group(1), "hash": m.group(2)}
+
+
+def _read_local_prompt_metadata() -> dict | None:
+    try:
+        return _parse_generated_prompt_metadata(_CLAUDE_PROMPT_PATH.read_text(encoding="utf-8"))
+    except OSError:
+        return None
+
+
+def _read_ref_prompt_metadata(ref: str = "origin/main") -> dict | None:
+    try:
+        proc = subprocess.run(
+            ["git", "show", f"{ref}:.claude/CLAUDE.md"],
+            capture_output=True, text=True, check=True, timeout=2,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return _parse_generated_prompt_metadata(proc.stdout)
+
+
+def _protocol_warning_text() -> str | None:
+    local_meta = _read_local_prompt_metadata()
+    ref_meta = _read_ref_prompt_metadata()
+    if not local_meta or not ref_meta:
+        return None
+    if local_meta["hash"] == ref_meta["hash"]:
+        return None
+    return (
+        "[CHERRYDOCS PROTOCOL WARNING] Local .claude/CLAUDE.md "
+        f"(version={local_meta['version']} hash={local_meta['hash']}) differs from "
+        f"origin/main (version={ref_meta['version']} hash={ref_meta['hash']}). "
+        "Sync from latest main if this branch is not intentionally changing prompt rules."
+    )
+
+
+# State helpers
+
+def _state_file(session_id: str | None = None) -> Path:
+    override = os.environ.get("CHERRY_HOOKS_STATE_FILE")
+    if override:
+        return Path(override)
+    if session_id:
+        safe = session_id[:12].replace("/", "_").replace(".", "_")
+        return Path(f".claude/hooks/session_{safe}.json")
+    return _STATE_FILE_DEFAULT
+
+
+def load_state(session_id: str | None = None) -> dict:
+    sf = _state_file(session_id)
+    if sf.exists():
+        try:
+            data = json.loads(sf.read_text(encoding="utf-8"))
+            # Forward-fill any keys added after this state file was created.
+            for k, v in _DEFAULTS.items():
+                data.setdefault(k, v)
+            return data
+        except (json.JSONDecodeError, OSError):
+            pass
+    return dict(_DEFAULTS)
+
+
+def save_state(state: dict, session_id: str | None = None) -> None:
+    sf = _state_file(session_id)
+    sf.parent.mkdir(parents=True, exist_ok=True)
+    sf.write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _minutes_since(iso: str | None) -> float | None:
+    if not iso:
+        return None
+    try:
+        dt = datetime.fromisoformat(iso)
+        return (datetime.now(timezone.utc) - dt).total_seconds() / 60
+    except ValueError:
+        return None
+
+
+def _load_transcript_messages(transcript_path: str | None) -> list[dict]:
+    if not transcript_path:
+        return []
+    try:
+        raw = Path(transcript_path).read_text(encoding="utf-8").strip()
+        try:
+            data = json.loads(raw)
+            messages = data if isinstance(data, list) else [data]
+        except json.JSONDecodeError:
+            messages = []
+            for line in raw.splitlines():
+                line = line.strip()
+                if line:
+                    try:
+                        messages.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        pass
+    except (OSError, ValueError, TypeError):
+        return []
+    return [msg for msg in messages if isinstance(msg, dict)]
+
+
+def _message_text(msg: dict) -> str:
+    content = msg.get("content", "")
+    if isinstance(content, list):
+        return " ".join(
+            block.get("text", "") if isinstance(block, dict) else str(block)
+            for block in content
+        ).strip()
+    return str(content).strip()
+
+
+def _latest_assistant_message(transcript_path: str | None) -> str | None:
+    for msg in reversed(_load_transcript_messages(transcript_path)):
+        role = msg.get("role") or msg.get("type", "")
+        if role != "assistant":
+            continue
+        text = _message_text(msg)
+        if text:
+            return text
+    return None
+
+
+def _assistant_message_from_event(event: dict | None) -> str | None:
+    if not isinstance(event, dict):
+        return None
+    direct = str(event.get("last_assistant_message") or "").strip()
+    if direct:
+        return direct
+    return _latest_assistant_message(event.get("transcript_path"))
+
+
+# ---------------------------------------------------------------------------
+# Command implementations
+# ---------------------------------------------------------------------------
+
+
+def cmd_session_start(session_id: str | None = None, event: dict | None = None) -> int:
+    """Print startup reminder once per fresh session; badge on every prompt."""
+    state = load_state(session_id)
+    payload = event if isinstance(event, dict) else {}
+    cwd = payload.get("cwd")
+    if not state.get("session_initialized"):
+        print(_STARTUP_REMINDER, end="")
+        state["session_initialized"] = True
+        # Protocol drift check: only run git subprocess once per session.
+        protocol_warning = _protocol_warning_text()
+        if protocol_warning:
+            print(protocol_warning)
+        save_state(state, session_id)
+        _append_capture_event(
+            CaptureEventType.SESSION_START,
+            session_id=session_id,
+            cwd=cwd,
+            metadata={"source": "claude-hooks"},
+        )
+    prompt = str(payload.get("prompt") or payload.get("text") or "").strip()
+    if prompt:
+        _append_capture_event(
+            CaptureEventType.USER_PROMPT,
+            session_id=session_id,
+            cwd=cwd,
+            text=prompt,
+            metadata={"source": "claude-hooks"},
+        )
+    # Nudge if edits were done without a log in this session.
+    edits = state.get("edits_since_last_log", 0)
+    if edits >= _LOG_NUDGE_AFTER_EDITS:
+        files = state.get("files_touched") or []
+        files_hint = f" (touched: {', '.join(files[-3:])})" if files else ""
+        print(
+            f"[CHERRYDOCS] {edits} edits since last log{files_hint}. "
+            "Log what you found before continuing."
+        )
+    return 0
+
+
+def cmd_post_tool_use(tool_name: str, session_id: str | None = None, event: dict | None = None) -> int:
+    """Update enforcement state based on the tool that was used."""
+    state = load_state(session_id)
+    event = event or {}
+
+    # Extract command + response before the dispatch block so all branches can use them.
+    raw_input = event.get("tool_input")
+    command = None
+    if isinstance(raw_input, dict):
+        command = str(raw_input.get("command") or raw_input.get("cmd") or "").strip() or None
+    exit_code = event.get("exit_code")
+    if not isinstance(exit_code, int):
+        exit_code = None
+    raw_response = event.get("tool_response") or event.get("tool_result")
+    response_text = raw_response.strip() if isinstance(raw_response, str) else None
+    if raw_response and not response_text and not isinstance(raw_response, str):
+        response_text = json.dumps(raw_response, ensure_ascii=False)
+
+    if tool_name in _CODE_TOOLS:
+        state["needs_log"] = True
+        state["needs_checkpoint"] = True
+        state["meaningful_work_done"] = True
+        state["edits_since_last_log"] = state.get("edits_since_last_log", 0) + 1
+        # Track which files were touched for specific stop messages.
+        file_path = _parse_edited_file(event)
+        if file_path:
+            touched = state.get("files_touched") or []
+            if file_path not in touched:
+                touched.append(file_path)
+            state["files_touched"] = touched[-10:]  # keep last 10
+
+    elif tool_name in _RUN_TOOLS:
+        # Detect a successful git commit and fire commit-anchored distillation immediately.
+        if command and re.search(r"\bgit\s+commit\b", command):
+            commit_hash = _parse_commit_hash(response_text)
+            if commit_hash:
+                state["last_commit_hash"] = commit_hash
+                _trigger_auto_distill(event.get("cwd"), commit_hash=commit_hash)
+
+    elif tool_name in _LOG_TOOLS:
+        state["needs_log"] = False
+        state["last_log_at"] = _now()
+        state["edits_since_last_log"] = 0
+        state["files_touched"] = []
+
+    elif tool_name in _CHECKPOINT_TOOLS:
+        state["needs_checkpoint"] = False
+        state["last_checkpoint_at"] = _now()
+
+    event_type = infer_capture_event_type(tool_name=tool_name, command=command)
+    _append_capture_event(
+        event_type,
+        session_id=session_id,
+        cwd=event.get("cwd"),
+        text=response_text,
+        command=command,
+        exit_code=exit_code,
+        metadata={"tool_name": tool_name},
+    )
+    save_state(state, session_id)
+    return 0
+
+
+def _check_no_log_in_transcript(transcript_path: str | None) -> bool:
+    """Return True if the last assistant message in the transcript contains [NO LOG:."""
+    latest = _latest_assistant_message(transcript_path)
+    return "[NO LOG:" in latest if latest else False
+
+
+_SUCCESS_OUTPUT = json.dumps({"continue": True, "suppressOutput": True})
+
+
+def _persist_session_id(session_id: str) -> None:
+    """Write session_id to disk so later hook calls can fall back to it."""
+    try:
+        _SESSION_ID_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _SESSION_ID_FILE.write_text(session_id, encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _read_persisted_session_id() -> str | None:
+    """Return the last session_id written by session-start, or None."""
+    try:
+        return _SESSION_ID_FILE.read_text(encoding="utf-8").strip() or None
+    except Exception:
+        return None
+
+
+def _parse_commit_hash(output: str | None) -> str | None:
+    """Extract abbreviated commit hash from `git commit` output like [main abc1234]."""
+    if not output:
+        return None
+    m = _GIT_COMMIT_OUTPUT_RE.search(output)
+    return m.group(1) if m else None
+
+
+def _trigger_auto_distill(cwd: str | None, commit_hash: str | None = None) -> None:
+    """Fire auto-promotion in background — does not block Stop hook."""
+    try:
+        from app.services.capture_core import capture_repo_context
+        from app.repo_scope import normalize_project_id
+        ctx = capture_repo_context(cwd)
+        project_id = normalize_project_id(ctx.get("repo") or Path(cwd or ".").name)
+        script = ROOT / "scripts" / "auto_promote_capture.py"
+        cmd = [
+            sys.executable, str(script),
+            "--project-id", project_id,
+            "--buffer-dir", str(_CAPTURE_BUFFER_ROOT.resolve()),
+            "--promoted-root", str(_PROMOTED_ROOT.resolve()),
+        ]
+        if commit_hash:
+            cmd += ["--commit-hash", commit_hash]
+        subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,  # detach fully — survives parent exit
+            cwd=str(ROOT),
+        )
+    except Exception:
+        pass  # never block the Stop hook
+
+
+def cmd_stop(
+    stop_hook_active: bool,
+    session_id: str | None = None,
+    transcript_path: str | None = None,
+    cwd: str | None = None,
+    event: dict | None = None,
+) -> int:
+    """Return 0 (allow stop) or 2 (block stop with specific message)."""
+    if stop_hook_active:
+        print(_SUCCESS_OUTPUT)
+        print("CherryDocs ✓ session ended", file=sys.stderr)
+        return 0
+
+    state = load_state(session_id)
+    issues: list[str] = []
+    latest_assistant = _assistant_message_from_event(event) or _latest_assistant_message(transcript_path)
+    no_log_declared = "[NO LOG:" in latest_assistant if latest_assistant else _check_no_log_in_transcript(transcript_path)
+    if latest_assistant:
+        _append_capture_event(
+            CaptureEventType.ASSISTANT_OUTPUT,
+            session_id=session_id,
+            cwd=cwd,
+            text=latest_assistant,
+            metadata={"source": "claude-hooks"},
+        )
+
+    if state.get("needs_log") and not no_log_declared:
+        files = state.get("files_touched") or []
+        edits = state.get("edits_since_last_log", 0)
+        files_hint = f": {', '.join(files[-3:])}" if files else ""
+        issues.append(
+            f"[CHERRYDOCS] Log required — {edits} edit(s) since last log{files_hint}.\n"
+            "  → mcp__cherry-docs__log_activity(type=..., summary=..., files=[...], reasoning=...)\n"
+            "  → Or write [NO LOG: <reason>] if nothing worth recording happened."
+        )
+
+    if state.get("needs_checkpoint") and state.get("meaningful_work_done"):
+        minutes = _minutes_since(state.get("last_checkpoint_at"))
+        age_hint = f" (last checkpoint {minutes:.0f}m ago)" if minutes else ""
+        issues.append(
+            f"[CHERRYDOCS] Checkpoint required before ending{age_hint}.\n"
+            "  → mcp__cherry-docs__save_checkpoint(summary=..., attempts=..., decisions=..., next_steps=[...])"
+        )
+
+    if issues:
+        print("\n".join(issues))
+        labels = []
+        if state.get("needs_log"):
+            labels.append("log")
+        if state.get("needs_checkpoint"):
+            labels.append("checkpoint")
+        print(f"CherryDocs ⚠ blocked: {' + '.join(labels)} required", file=sys.stderr)
+        return 2
+    _trigger_auto_distill(cwd)
+    print(_SUCCESS_OUTPUT)
+    edits = state.get("edits_since_last_log", 0)
+    status = "no edits" if not edits else f"{edits} edit(s) logged"
+    print(f"CherryDocs ✓ {status}", file=sys.stderr)
+    return 0
+
+
+def cmd_reset(session_id: str | None = None) -> int:
+    """Clear session state."""
+    sf = _state_file(session_id)
+    if sf.exists():
+        sf.unlink()
+    print("Session state cleared.")
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: state_manager.py <session-start|post-tool-use|stop|reset>", file=sys.stderr)
+        return 1
+
+    cmd = sys.argv[1]
+    raw_stdin = sys.stdin.read()
+
+    try:
+        event: dict = json.loads(raw_stdin) if raw_stdin.strip() else {}
+    except json.JSONDecodeError:
+        event = {}
+
+    session_id: str | None = event.get("session_id") or _read_persisted_session_id()
+
+    # Persist on every hook that carries a session_id — not just session-start.
+    # This ensures Stop can always find the right state file even if it doesn't
+    # receive session_id in its own payload.
+    if event.get("session_id"):
+        _persist_session_id(event["session_id"])
+
+    if cmd == "session-start":
+        return cmd_session_start(session_id, event)
+
+    if cmd == "post-tool-use":
+        return cmd_post_tool_use(event.get("tool_name", ""), session_id, event)
+
+    if cmd == "stop":
+        return cmd_stop(
+            bool(event.get("stop_hook_active", False)),
+            session_id,
+            event.get("transcript_path"),
+            event.get("cwd"),
+            event,
+        )
+
+    if cmd == "reset":
+        return cmd_reset(session_id)
+
+    print(f"Unknown command: {cmd}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/coverage_regression_gate.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Summarize coverage XML and enforce a baseline regression gate."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any
+
+
+def _load_json(path: str | Path) -> dict[str, Any]:
+    return json.loads(Path(path).read_text())
+
+
+def _load_coverage_xml(path: str | Path) -> dict[str, Any]:
+    root = ET.fromstring(Path(path).read_text())
+    return {
+        "line_rate": round(float(root.attrib.get("line-rate", 0.0)) * 100, 2),
+        "branch_rate": round(float(root.attrib.get("branch-rate", 0.0)) * 100, 2),
+        "lines_covered": int(root.attrib.get("lines-covered", 0)),
+        "lines_valid": int(root.attrib.get("lines-valid", 0)),
+        "branches_covered": int(root.attrib.get("branches-covered", 0)),
+        "branches_valid": int(root.attrib.get("branches-valid", 0)),
+    }
+
+
+def _write_json(path: str | None, payload: dict[str, Any]) -> None:
+    if not path:
+        return
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+
+def _compare(
+    baseline: dict[str, Any],
+    candidate: dict[str, Any],
+    *,
+    min_line_rate: float,
+    max_line_drop: float,
+) -> tuple[dict[str, Any], list[str]]:
+    errors: list[str] = []
+    line_drop = round(float(baseline.get("line_rate", 0.0)) - float(candidate.get("line_rate", 0.0)), 2)
+    branch_drop = round(float(baseline.get("branch_rate", 0.0)) - float(candidate.get("branch_rate", 0.0)), 2)
+
+    if float(candidate.get("line_rate", 0.0)) < min_line_rate:
+        errors.append(
+            f"line coverage {candidate['line_rate']:.2f}% is below minimum {min_line_rate:.2f}%"
+        )
+    if line_drop > max_line_drop:
+        errors.append(
+            f"line coverage dropped by {line_drop:.2f} points, exceeding max drop {max_line_drop:.2f}"
+        )
+
+    report = {
+        "baseline_line_rate": baseline.get("line_rate"),
+        "candidate_line_rate": candidate.get("line_rate"),
+        "line_rate_drop": line_drop,
+        "baseline_branch_rate": baseline.get("branch_rate"),
+        "candidate_branch_rate": candidate.get("branch_rate"),
+        "branch_rate_drop": branch_drop,
+        "min_line_rate": min_line_rate,
+        "max_line_drop": max_line_drop,
+        "baseline_lines_covered": baseline.get("lines_covered"),
+        "candidate_lines_covered": candidate.get("lines_covered"),
+        "baseline_lines_valid": baseline.get("lines_valid"),
+        "candidate_lines_valid": candidate.get("lines_valid"),
+        "errors": errors,
+    }
+    return report, errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--candidate", required=True, help="Coverage XML file to summarize.")
+    parser.add_argument("--baseline", help="Baseline coverage summary JSON to compare against.")
+    parser.add_argument("--summary-output", help="Where to write the normalized coverage summary JSON.")
+    parser.add_argument("--report-output", help="Where to write the comparison report JSON.")
+    parser.add_argument("--min-line-rate", type=float, default=70.0)
+    parser.add_argument("--max-line-drop", type=float, default=3.0)
+    args = parser.parse_args()
+
+    candidate = _load_coverage_xml(args.candidate)
+    _write_json(args.summary_output, candidate)
+
+    print(
+        "Coverage summary:",
+        f"line={candidate['line_rate']:.2f}%",
+        f"branch={candidate['branch_rate']:.2f}%",
+        f"covered={candidate['lines_covered']}/{candidate['lines_valid']}",
+    )
+
+    if not args.baseline:
+        return 0
+
+    baseline = _load_json(args.baseline)
+    report, errors = _compare(
+        baseline,
+        candidate,
+        min_line_rate=args.min_line_rate,
+        max_line_drop=args.max_line_drop,
+    )
+    _write_json(args.report_output, report)
+
+    print(
+        "Coverage regression:",
+        f"baseline={report['baseline_line_rate']:.2f}%",
+        f"candidate={report['candidate_line_rate']:.2f}%",
+        f"drop={report['line_rate_drop']:.2f}",
+    )
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())