@ahmed-g-gad/apothem 0.1.1

package/src/apothem/hooks/emit_hook_context.py

@@ -0,0 +1,444 @@
+# SPDX-License-Identifier: MIT
+
+"""Emit structured JSON context for supported harness hook events.
+
+Two modes of operation:
+
+* **Hook mode** — when both ``--hook-event-name`` and ``--context-file``
+  are supplied, read a context-message file plus hook metadata from
+  stdin and emit a single-line ``hookSpecificOutput`` envelope.
+* **Diagnostic mode** — when either argument is absent, print a human-
+  readable ecosystem summary (counts of rules/commands/agents/skills
+  and presence of core files).
+
+On any unexpected failure, emit a valid JSON envelope with a failure
+message and exit 0 — never surface raw tracebacks to the hook runtime.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Final
+
+_LIB_DIR: Final[Path] = Path(__file__).resolve().parent / "lib"
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+from events import (
+    HOOK_SPECIFIC_OUTPUT_EVENTS as _HOOK_SPECIFIC_OUTPUT_EVENTS,
+)
+from log import get_logger
+from resolve_root import Mode, resolve_project_root
+
+_logger = get_logger(__name__)
+
+_UNICODE_MAP: Final[dict[str, str]] = {
+    "\u2013": "-",
+    "\u2014": "-",
+    "\u2018": "'",
+    "\u2019": "'",
+    "\u201c": '"',
+    "\u201d": '"',
+    "\u00d7": "x",
+    "\u2212": "-",
+    "\u2192": "->",
+    "\u2264": "<=",
+}
+
+_NON_ASCII = re.compile(r"[^\x00-\x7f]")
+
+
+def normalize_ascii(text: str) -> str:
+    """Map common typographic Unicode to ASCII, strip remaining non-ASCII."""
+    if not text:
+        return ""
+    for source, target in _UNICODE_MAP.items():
+        text = text.replace(source, target)
+    return _NON_ASCII.sub("", text)
+
+
+def read_hook_stdin() -> dict[str, object] | None:
+    """Read and parse the hook's stdin JSON payload, if any."""
+    if sys.stdin.isatty():
+        return None
+    try:
+        raw = sys.stdin.read()
+    except OSError:
+        return None
+    if not raw or not raw.strip():
+        return None
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def build_metadata_prefix(payload: dict[str, object] | None) -> str:
+    """Return a bracketed metadata prefix, or empty string when absent."""
+    if not payload:
+        return ""
+    parts: list[str] = []
+    for field, label in (
+        ("source", "source"),
+        ("tool_name", "tool"),
+        ("matcher", "matcher"),
+    ):
+        value = payload.get(field)
+        if isinstance(value, str) and value:
+            parts.append(f"{label}={value}")
+    return f"[{' | '.join(parts)}]" if parts else ""
+
+
+_BASH_GIT_TRIGGERS: Final[tuple[str, ...]] = (
+    "git commit",
+    "git checkout -b",
+    "git branch",
+    "git tag",
+    "git merge -m",
+    "git rebase --exec",
+    "git stash push -m",
+    "git notes add",
+    "git mv",
+    "git rm",
+)
+
+_PASS_SUPPRESSED_PRETOOLUSE_MESSAGES: Final[frozenset[str]] = frozenset(
+    {
+        "pretooluse-write.md",
+        "pretooluse-edit.md",
+        "pretooluse-notebookedit.md",
+        "pretooluse-conformity.md",
+    }
+)
+
+_HEADER_GUARD_MESSAGES: Final[frozenset[str]] = frozenset(
+    {
+        "pretooluse-write-header-guard.md",
+        "pretooluse-edit-header-guard.md",
+    }
+)
+
+_PLAN_GUARD_MESSAGES: Final[frozenset[str]] = frozenset(
+    {
+        "pretooluse-write-plan-guard.md",
+        "pretooluse-bash-plan-guard.md",
+    }
+)
+
+_PLAN_SHAPED_MARKERS: Final[tuple[str, ...]] = (
+    "master-plan:",
+    "phase-id:",
+    "phases:",
+    "resumption contract",
+    "phase output registry",
+)
+
+_PLAN_PATH_MARKERS: Final[tuple[str, ...]] = (
+    ".plans/",
+    ".plans\\",
+    "/plans/",
+    "\\plans\\",
+)
+
+
+def should_suppress_bash_hook(
+    event_name: str,
+    context_file: str,
+    payload: dict[str, object] | None,
+) -> bool:
+    """Return True when a Bash PreToolUse hook should emit no context.
+
+    The pretooluse-bash context message is a git-artifact-isolation
+    reminder keyed to the fixed git-mutation trigger set above. For
+    non-git Bash invocations the message adds noise, so the hook emits
+    an empty envelope instead. Mirrors the trigger declaration in
+    ``hooks/messages/pretooluse-bash.md`` to preserve the message-
+    dispatcher paired-shape invariant.
+    """
+    if event_name != "PreToolUse":
+        return False
+    if not context_file.endswith("pretooluse-bash.md"):
+        return False
+    if not payload or payload.get("tool_name") != "Bash":
+        return False
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return False
+    command = tool_input.get("command")
+    if not isinstance(command, str):
+        return False
+    return not any(trigger in command for trigger in _BASH_GIT_TRIGGERS)
+
+
+def _context_basename(context_file: str) -> str:
+    return Path(context_file).name
+
+
+def _tool_input(payload: dict[str, object] | None) -> dict[str, object]:
+    if not payload:
+        return {}
+    raw = payload.get("tool_input")
+    return raw if isinstance(raw, dict) else {}
+
+
+def _path_from_tool_input(tool_input: dict[str, object]) -> str:
+    for key in ("file_path", "path", "notebook_path"):
+        value = tool_input.get(key)
+        if isinstance(value, str):
+            return value
+    return ""
+
+
+def _text_from_tool_input(tool_input: dict[str, object]) -> str:
+    chunks: list[str] = []
+    for key in ("content", "new_string", "command", "cell_source"):
+        value = tool_input.get(key)
+        if isinstance(value, str):
+            chunks.append(value)
+    return "\n".join(chunks)
+
+
+def _nearest_git_root(start: Path) -> Path:
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+    for candidate in (current, *current.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return current
+
+
+def _is_project_local_plan_path(path: str) -> bool:
+    if not path:
+        return False
+    try:
+        candidate = Path(path).expanduser()
+        if not candidate.is_absolute():
+            candidate = Path.cwd() / candidate
+        resolved = candidate.resolve()
+        root = _nearest_git_root(Path.cwd())
+        resolved.relative_to(root)
+    except (OSError, RuntimeError, ValueError):
+        return False
+    return ".plans" in resolved.parts
+
+
+def _looks_plan_shaped(path: str, text: str) -> bool:
+    if _is_project_local_plan_path(path):
+        return False
+    haystack = f"{path}\n{text}".lower().replace("\\", "/")
+    if any(marker.replace("\\", "/") in haystack for marker in _PLAN_PATH_MARKERS):
+        return True
+    return any(marker in haystack for marker in _PLAN_SHAPED_MARKERS)
+
+
+def _missing_header(path: str, text: str) -> bool:
+    if not path or not text:
+        return False
+    try:
+        from apothem.conformity import file_header_grep
+
+        result = file_header_grep.check(text, Path(path))
+    except Exception as exc:  # code-craft-boundary: broad-except; fail-closed guard.
+        # Fail closed (treat as header-absent) but surface the failing class so
+        # a genuine internal defect in file_header_grep.check is distinguishable
+        # from a true header-absent verdict rather than silently masked.
+        _logger.warning(
+            "file_header_grep.check raised %s for %s; failing closed",
+            type(exc).__name__,
+            path,
+        )
+        return True
+    return not result.passed
+
+
+def should_suppress_pretooluse_context(
+    event_name: str,
+    context_file: str,
+    payload: dict[str, object] | None,
+) -> bool:
+    """Suppress allow-class PreToolUse context messages.
+
+    The actual conformity hooks still run. This emitter only controls
+    advisory context volume, so pass-class tool calls should return an
+    empty envelope and reserve prose for findings or guarded actions.
+    """
+    if event_name != "PreToolUse":
+        return False
+    basename = _context_basename(context_file)
+    if basename in _PASS_SUPPRESSED_PRETOOLUSE_MESSAGES:
+        return True
+    tool_input = _tool_input(payload)
+    path = _path_from_tool_input(tool_input)
+    text = _text_from_tool_input(tool_input)
+    if basename in _PLAN_GUARD_MESSAGES:
+        return not _looks_plan_shaped(path, text)
+    if basename in _HEADER_GUARD_MESSAGES:
+        return not _missing_header(path, text)
+    return False
+
+
+def compose_context(message: str, payload: dict[str, object] | None) -> str:
+    """Combine a metadata prefix (if any) with the message body."""
+    prefix = build_metadata_prefix(payload)
+    body = message or ""
+    if prefix and body:
+        return f"{prefix}\n{body}"
+    return prefix or body
+
+
+def resolve_context_path(context_file: str, root: Path) -> Path | None:
+    """Return `context_file` as an absolute path within `root`.
+
+    Absolute paths are accepted as-is (the caller — typically a hook
+    configuration in ``settings.json`` — explicitly chose them). Relative
+    paths are joined against `root` and verified not to escape it via
+    parent-directory traversal; on escape, returns ``None`` so the caller
+    can decline the read instead of leaking arbitrary file contents.
+    """
+    candidate = Path(context_file)
+    if candidate.is_absolute():
+        return candidate
+    resolved = (root / candidate).resolve()
+    try:
+        resolved.relative_to(root.resolve())
+    except ValueError:
+        return None
+    return resolved
+
+
+def build_envelope(event_name: str, additional_context: str) -> dict[str, object]:
+    """Return the schema-valid envelope for `event_name`."""
+    if event_name in _HOOK_SPECIFIC_OUTPUT_EVENTS:
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": event_name,
+                "additionalContext": additional_context,
+            }
+        }
+    return {"systemMessage": additional_context}
+
+
+def emit_hook_envelope(event_name: str, additional_context: str, quiet: bool) -> None:
+    """Print the schema-appropriate JSON envelope (unless quiet)."""
+    envelope = build_envelope(event_name, additional_context)
+    if not quiet:
+        sys.stdout.write(json.dumps(envelope, separators=(",", ":")) + "\n")
+
+
+def emit_failure_envelope(event_name: str, message: str) -> None:
+    """Print a failure envelope to stdout; used as the last-resort path."""
+    envelope = build_envelope(
+        event_name or "UnknownEvent",
+        f"Hook execution failure: {message}",
+    )
+    sys.stdout.write(json.dumps(envelope, separators=(",", ":")) + "\n")
+
+
+def run_hook_mode(
+    event_name: str,
+    context_file: str,
+    quiet: bool,
+    root: Path,
+) -> None:
+    """Read context file + stdin, emit the hook envelope."""
+    resolved = resolve_context_path(context_file, root)
+    message = ""
+    if resolved is None:
+        _logger.warning("Refusing context path outside root: %s", context_file)
+    elif resolved.is_file():
+        try:
+            message = resolved.read_text(encoding="utf-8")
+        except OSError as exc:
+            _logger.debug("Context file unreadable: %s", exc)
+
+    payload = read_hook_stdin()
+    if should_suppress_bash_hook(event_name, context_file, payload):
+        emit_hook_envelope(event_name, "", quiet)
+        return
+    if should_suppress_pretooluse_context(event_name, context_file, payload):
+        emit_hook_envelope(event_name, "", quiet)
+        return
+    combined = compose_context(message, payload)
+    additional = normalize_ascii(combined)
+    emit_hook_envelope(event_name, additional, quiet)
+
+
+def run_diagnostic_mode(root: Path) -> None:
+    """Print a human-readable ecosystem summary.
+
+    Uses ``print`` deliberately: this is the diagnostic CLI surface, not
+    operational logging. ``logging`` would route through handlers that the
+    CLI runner doesn't necessarily configure.
+    """
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    print("=== Apothem Ecosystem Diagnostics ===")
+    print(f"Timestamp: {now}")
+    print(f"PROJECT_ROOT: {root}")
+    print()
+
+    counts: dict[str, int] = {
+        "Rules": _count(root / "rules", "*.md"),
+        "Commands": _count(root / "commands", "*.md"),
+        "Agents": _count(root / "agents", "*.md", recursive=False),
+        "Skills": _count(root / "skills", "SKILL.md", recursive=True),
+    }
+    print("  ".join(f"{k}: {v}" for k, v in counts.items()))
+    print()
+
+    probes = (
+        "CLAUDE.md",
+        "settings.json",
+        "site/content/docs/reference/settings-reference.mdx",
+        "hooks/emit_hook_context.py",
+        "hooks/session_start_bootstrap.py",
+    )
+    for rel in probes:
+        marker = "+" if (root / rel).exists() else "-"
+        print(f"{marker} {rel}")
+
+
+def _count(directory: Path, pattern: str, *, recursive: bool = False) -> int:
+    """Return the number of files matching `pattern` in `directory`."""
+    if not directory.is_dir():
+        return 0
+    matcher = directory.rglob if recursive else directory.glob
+    return sum(1 for _ in matcher(pattern))
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parse CLI arguments."""
+    parser = argparse.ArgumentParser(
+        prog="emit_hook_context",
+        description="Emit hook context as structured JSON.",
+    )
+    parser.add_argument("--hook-event-name", "-n", default="")
+    parser.add_argument("--context-file", "-c", default="")
+    parser.add_argument("--quiet", "-q", action="store_true")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point. Guarantees a valid JSON envelope on any failure."""
+    args = parse_args(argv)
+    try:
+        root = resolve_project_root(Mode.HOOKS, script_path=Path(__file__))
+        if root is None:
+            root = Path(__file__).resolve().parent.parent
+
+        if not args.hook_event_name or not args.context_file:
+            run_diagnostic_mode(root)
+            return
+        run_hook_mode(args.hook_event_name, args.context_file, args.quiet, root)
+    except Exception as exc:
+        emit_failure_envelope(args.hook_event_name, str(exc))
+
+
+if __name__ == "__main__":
+    main()