code-muse 0.0.1__py3-none-any.whl

code_muse/hook_engine/models.py

@@ -0,0 +1,245 @@
+"""
+Data models for the hook engine.
+
+Defines all data structures used throughout the hook engine with full type
+safety and validation.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass
+class HookConfig:
+    """
+    Configuration for a single hook.
+
+    Attributes:
+        matcher: Pattern to match against events (e.g., "Edit && .py")
+        type: Type of hook action ("command" or "prompt")
+        command: Command or prompt text to execute
+        timeout: Maximum execution time in milliseconds (default: 5000)
+        once: Execute only once per session (default: False)
+        enabled: Whether this hook is enabled (default: True)
+        id: Optional unique identifier for this hook
+        source: Origin of the hook config ("global" or "project")
+        trusted: Whether this hook has been explicitly trusted. For global
+            hooks this defaults to True. Project hooks default to False.
+    """
+
+    matcher: str
+    type: Literal["command", "prompt"]
+    command: str
+    timeout: int = 5000
+    once: bool = False
+    enabled: bool = True
+    id: str | None = None
+    source: Literal["global", "project"] = "global"
+    trusted: bool = True
+
+    def __post_init__(self):
+        """Validate hook configuration after initialization."""
+        if not self.matcher:
+            raise ValueError("Hook matcher cannot be empty")
+
+        if self.type not in ("command", "prompt"):
+            raise ValueError(
+                f"Hook type must be 'command' or 'prompt', got: {self.type}"
+            )
+
+        if not self.command:
+            raise ValueError("Hook command cannot be empty")
+
+        if self.timeout < 100:
+            raise ValueError(f"Hook timeout must be >= 100ms, got: {self.timeout}")
+
+        if self.id is None:
+            import hashlib
+
+            content = f"{self.matcher}:{self.type}:{self.command}"
+            self.id = hashlib.sha256(content.encode()).hexdigest()[:12]
+
+
+@dataclass
+class EventData:
+    """
+    Input data for hook processing.
+
+    Attributes:
+        event_type: Type of event (PreToolUse, PostToolUse, etc.)
+        tool_name: Name of the tool being called
+        tool_args: Arguments passed to the tool
+        context: Optional context metadata (result, duration, etc.)
+    """
+
+    event_type: str
+    tool_name: str
+    tool_args: dict[str, Any] = field(default_factory=dict)
+    context: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if not self.event_type:
+            raise ValueError("Event type cannot be empty")
+        if not self.tool_name:
+            raise ValueError("Tool name cannot be empty")
+
+
+@dataclass
+class ExecutionResult:
+    """
+    Result from executing a hook.
+
+    Attributes:
+        blocked: Whether the hook blocked the operation
+        hook_command: The command that was executed
+        stdout: Standard output from command
+        stderr: Standard error from command
+        exit_code: Exit code from command execution
+        duration_ms: Execution duration in milliseconds
+        error: Error message if execution failed
+        hook_id: ID of the hook that was executed
+    """
+
+    blocked: bool
+    hook_command: str
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int = 0
+    duration_ms: float = 0.0
+    error: str | None = None
+    hook_id: str | None = None
+
+    @property
+    def success(self) -> bool:
+        """Whether the hook executed successfully (exit code 0)."""
+        return self.exit_code == 0 and self.error is None
+
+    @property
+    def output(self) -> str:
+        """Combined stdout and stderr."""
+        parts = []
+        if self.stdout:
+            parts.append(self.stdout)
+        if self.stderr:
+            parts.append(self.stderr)
+        return "\n".join(parts)
+
+
+@dataclass
+class HookGroup:
+    """A group of hooks that share the same matcher."""
+
+    matcher: str
+    hooks: list[HookConfig] = field(default_factory=list)
+
+    def __post_init__(self):
+        if not self.matcher:
+            raise ValueError("Hook group matcher cannot be empty")
+
+
+@dataclass
+class HookRegistry:
+    """Registry of all hooks organized by event type."""
+
+    pre_tool_use: list[HookConfig] = field(default_factory=list)
+    post_tool_use: list[HookConfig] = field(default_factory=list)
+    session_start: list[HookConfig] = field(default_factory=list)
+    session_end: list[HookConfig] = field(default_factory=list)
+    pre_compact: list[HookConfig] = field(default_factory=list)
+    user_prompt_submit: list[HookConfig] = field(default_factory=list)
+    notification: list[HookConfig] = field(default_factory=list)
+    stop: list[HookConfig] = field(default_factory=list)
+    subagent_stop: list[HookConfig] = field(default_factory=list)
+
+    _executed_once_hooks: set = field(default_factory=set, repr=False)
+
+    def get_hooks_for_event(self, event_type: str) -> list[HookConfig]:
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            return []
+        all_hooks = getattr(self, attr_name)
+        enabled_hooks = []
+        for hook in all_hooks:
+            if not hook.enabled:
+                continue
+            if hook.once and hook.id in self._executed_once_hooks:
+                continue
+            enabled_hooks.append(hook)
+        return enabled_hooks
+
+    def mark_hook_executed(self, hook_id: str) -> None:
+        self._executed_once_hooks.add(hook_id)
+
+    def reset_once_hooks(self) -> None:
+        self._executed_once_hooks.clear()
+
+    @staticmethod
+    def _normalize_event_type(event_type: str) -> str:
+        import re
+
+        s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", event_type)
+        return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+
+    def add_hook(self, event_type: str, hook: HookConfig) -> None:
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            raise ValueError(f"Unknown event type: {event_type}")
+        getattr(self, attr_name).append(hook)
+
+    def remove_hook(self, event_type: str, hook_id: str) -> bool:
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            return False
+        hooks_list = getattr(self, attr_name)
+        for i, hook in enumerate(hooks_list):
+            if hook.id == hook_id:
+                hooks_list.pop(i)
+                return True
+        return False
+
+    def count_hooks(self, event_type: str | None = None) -> int:
+        if event_type is None:
+            total = 0
+            for attr in [
+                "pre_tool_use",
+                "post_tool_use",
+                "session_start",
+                "session_end",
+                "pre_compact",
+                "user_prompt_submit",
+                "notification",
+                "stop",
+                "subagent_stop",
+            ]:
+                total += len(getattr(self, attr))
+            return total
+        attr_name = self._normalize_event_type(event_type)
+        if not hasattr(self, attr_name):
+            return 0
+        return len(getattr(self, attr_name))
+
+
+@dataclass
+class ProcessEventResult:
+    """Result from processing an event through the hook engine."""
+
+    blocked: bool
+    executed_hooks: int
+    results: list[ExecutionResult]
+    blocking_reason: str | None = None
+    total_duration_ms: float = 0.0
+
+    @property
+    def all_successful(self) -> bool:
+        return all(result.success for result in self.results)
+
+    @property
+    def failed_hooks(self) -> list[ExecutionResult]:
+        return [result for result in self.results if not result.success]
+
+    def get_combined_output(self) -> str:
+        outputs = []
+        for result in self.results:
+            if result.output:
+                outputs.append(f"[{result.hook_command}]\n{result.output}")
+        return "\n\n".join(outputs)

code_muse/hook_engine/registry.py

@@ -0,0 +1,114 @@
+"""
+Registry management for hooks.
+
+Builds and manages the HookRegistry from configuration dictionaries.
+"""
+
+import logging
+import re
+from typing import Any
+
+from .models import HookConfig, HookRegistry
+
+logger = logging.getLogger(__name__)
+
+# Supported event types
+SUPPORTED_EVENT_TYPES = [
+    "PreToolUse",
+    "PostToolUse",
+    "SessionStart",
+    "SessionEnd",
+    "PreCompact",
+    "UserPromptSubmit",
+    "Notification",
+    "Stop",
+    "SubagentStop",
+]
+
+
+def build_registry_from_config(
+    config: dict[str, Any],
+    source: str = "global",
+    trusted: bool = True,
+) -> HookRegistry:
+    """
+    Build a HookRegistry from a configuration dictionary.
+
+    Args:
+        config: Hook configuration dictionary.
+        source: Origin of this config ("global" or "project").
+        trusted: Whether hooks from this config are pre-trusted.
+
+    Returns:
+        Populated HookRegistry
+    """
+    registry = HookRegistry()
+
+    for event_type, hook_groups in config.items():
+        if event_type.startswith("_"):
+            continue  # skip comment keys
+
+        if not isinstance(hook_groups, list):
+            logger.warning(f"Hook groups for '{event_type}' must be a list, skipping")
+            continue
+
+        for group in hook_groups:
+            if not isinstance(group, dict):
+                continue
+
+            matcher = group.get("matcher", "*")
+            hooks_data = group.get("hooks", [])
+
+            for hook_data in hooks_data:
+                if not isinstance(hook_data, dict):
+                    continue
+                if hook_data.get("type") == "command" and not hook_data.get("command"):
+                    continue
+
+                try:
+                    hook = HookConfig(
+                        matcher=matcher,
+                        type=hook_data.get("type", "command"),
+                        command=hook_data.get("command", hook_data.get("prompt", "")),
+                        timeout=hook_data.get("timeout", 5000),
+                        once=hook_data.get("once", False),
+                        enabled=hook_data.get("enabled", True),
+                        id=hook_data.get("id"),
+                        source=source,  # type: ignore[arg-type]
+                        trusted=trusted,
+                    )
+                    registry.add_hook(event_type, hook)
+                except (ValueError, KeyError) as e:
+                    logger.warning(f"Skipping invalid hook in {event_type}: {e}")
+
+    return registry
+
+
+def get_registry_stats(registry: HookRegistry) -> dict[str, Any]:
+    """Get statistics about a registry."""
+    stats: dict[str, Any] = {
+        "total_hooks": registry.count_hooks(),
+        "enabled_hooks": 0,
+        "disabled_hooks": 0,
+        "by_event": {},
+    }
+
+    def _to_attr(event_type: str) -> str:
+        s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", event_type)
+        return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+
+    for event_type in SUPPORTED_EVENT_TYPES:
+        attr = _to_attr(event_type)
+        hooks = getattr(registry, attr, [])
+        enabled = sum(1 for h in hooks if h.enabled)
+        disabled = len(hooks) - enabled
+        stats["enabled_hooks"] += enabled
+        stats["disabled_hooks"] += disabled
+        if hooks:
+            stats["by_event"][event_type] = {
+                "total": len(hooks),
+                "enabled": enabled,
+                "disabled": disabled,
+            }
+
+    return stats

code_muse/hook_engine/trust.py

@@ -0,0 +1,268 @@
+"""Hook trust engine for project-level hooks.
+
+Requires explicit user trust before executing repository-controlled hooks.
+Trust decisions are stored privately in XDG state and keyed by:
+  - project root directory
+  - hooks file path
+  - content hash (SHA-256 of hooks file)
+
+This prevents repo-controlled hooks from executing automatically after
+cloning or when content changes.
+"""
+
+import contextlib
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# XDG state directory for private trust storage
+_TRUST_DIR = (
+    Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local" / "state"))
+    / "code_muse"
+)
+_TRUST_FILE = _TRUST_DIR / "hook_trust.json"
+
+# Minimal env vars allowed for project hooks
+_SAFE_ENV_ALLOWLIST = {
+    "PATH",
+    "HOME",
+    "SHELL",
+    "PWD",
+    "TERM",
+    "LANG",
+    "LC_ALL",
+    "USER",
+    "LOGNAME",
+    "CLAUDE_PROJECT_DIR",
+    "CLAUDE_TOOL_INPUT",
+    "CLAUDE_TOOL_NAME",
+    "CLAUDE_HOOK_EVENT",
+    "CLAUDE_CODE_HOOK",
+    "CLAUDE_FILE_PATH",
+}
+
+# Patterns that suggest a secret-bearing env var
+_SECRET_ENV_PATTERNS = (
+    "token",
+    "secret",
+    "password",
+    "passwd",
+    "api_key",
+    "apikey",
+    "auth",
+    "credential",
+    "private_key",
+    "ssh_key",
+    "aws_access",
+    "aws_secret",
+    "bearer",
+    "jwt",
+    "client_secret",
+    "access_token",
+    "refresh_token",
+    "id_token",
+)
+
+
+def _ensure_private_dir(path: Path) -> Path:
+    """Ensure directory exists with 0o700 permissions."""
+    path.mkdir(parents=True, exist_ok=True)
+    with contextlib.suppress(OSError):
+        os.chmod(path, 0o700)
+    return path
+
+
+def _atomic_write_private_json(file_path: Path, data: dict) -> None:
+    """Atomically write JSON with 0o600 permissions."""
+    tmp_path = file_path.with_suffix(".tmp")
+    try:
+        fd = os.open(
+            str(tmp_path),
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            0o600,
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(str(tmp_path), str(file_path))
+        with contextlib.suppress(OSError):
+            os.chmod(file_path, 0o600)
+    except Exception:
+        with contextlib.suppress(OSError):
+            tmp_path.unlink(missing_ok=True)
+        raise
+
+
+def _load_trust_db() -> dict[str, dict]:
+    """Load the trust database from private storage."""
+    _ensure_private_dir(_TRUST_DIR)
+    if not _TRUST_FILE.exists():
+        return {}
+    try:
+        with open(_TRUST_FILE, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data
+    except json.JSONDecodeError, OSError:
+        pass
+    return {}
+
+
+def _save_trust_db(db: dict[str, dict]) -> None:
+    """Save the trust database to private storage."""
+    _ensure_private_dir(_TRUST_DIR)
+    _atomic_write_private_json(_TRUST_FILE, db)
+
+
+def _compute_trust_key(
+    project_root: str | Path,
+    hooks_file_path: str | Path,
+    content_hash: str,
+) -> str:
+    """Compute a deterministic trust key."""
+    raw = f"{project_root}\n{hooks_file_path}\n{content_hash}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def compute_content_hash(content: str) -> str:
+    """Compute SHA-256 hash of hook file content."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def is_hook_trusted(
+    project_root: str | Path,
+    hooks_file_path: str | Path,
+    content_hash: str,
+) -> bool:
+    """Check whether a project hook file is explicitly trusted.
+
+    Args:
+        project_root: Absolute path to the project root directory.
+        hooks_file_path: Absolute path to the hooks configuration file.
+        content_hash: SHA-256 hash of the current hooks file content.
+
+    Returns:
+        True if the user has previously approved this exact content.
+    """
+    db = _load_trust_db()
+    key = _compute_trust_key(project_root, hooks_file_path, content_hash)
+    entry = db.get(key)
+    if entry is None:
+        return False
+    stored_hash = entry.get("content_hash")
+    if stored_hash != content_hash:
+        return False
+    return entry.get("trusted", False)
+
+
+def approve_hook(
+    project_root: str,
+    hooks_file_path: str,
+    content_hash: str,
+) -> None:
+    """Explicitly mark a project hook file as trusted.
+
+    Args:
+        project_root: Absolute path to the project root directory.
+        hooks_file_path: Absolute path to the hooks configuration file.
+        content_hash: SHA-256 hash of the current hooks file content.
+    """
+    db = _load_trust_db()
+    key = _compute_trust_key(project_root, hooks_file_path, content_hash)
+    db[key] = {
+        "project_root": project_root,
+        "hooks_file_path": hooks_file_path,
+        "content_hash": content_hash,
+        "trusted": True,
+    }
+    _save_trust_db(db)
+    logger.info(f"Hook trusted: {hooks_file_path} (hash={content_hash[:16]}...)")
+
+
+def revoke_hook_trust(
+    project_root: str,
+    hooks_file_path: str,
+) -> None:
+    """Revoke trust for a project hook file regardless of content hash.
+
+    Args:
+        project_root: Absolute path to the project root directory.
+        hooks_file_path: Absolute path to the hooks configuration file.
+    """
+    db = _load_trust_db()
+    keys_to_remove = []
+    for key, entry in db.items():
+        if (
+            entry.get("project_root") == project_root
+            and entry.get("hooks_file_path") == hooks_file_path
+        ):
+            keys_to_remove.append(key)
+    for key in keys_to_remove:
+        del db[key]
+    if keys_to_remove:
+        _save_trust_db(db)
+        logger.info(f"Hook trust revoked: {hooks_file_path}")
+
+
+def build_minimal_hook_env(base_env: dict[str, str | None] = None) -> dict[str, str]:
+    """Build a minimal environment dict for project hooks.
+
+    Strips secret-like environment variables while preserving safe
+    operational variables and any hook-specific vars.
+
+    Args:
+        base_env: Optional base environment to filter. Defaults to os.environ.
+
+    Returns:
+        Filtered environment dictionary.
+    """
+    env = base_env if base_env is not None else os.environ.copy()
+    filtered: dict[str, str] = {}
+    for key, value in env.items():
+        upper_key = key.upper()
+        # Always allow safe vars
+        if upper_key in _SAFE_ENV_ALLOWLIST:
+            filtered[key] = value
+            continue
+        # Block anything that looks secret-bearing
+        lower_key = key.lower()
+        if any(pattern in lower_key for pattern in _SECRET_ENV_PATTERNS):
+            continue
+        # Block very long values that might be tokens/keys
+        if len(value) > 4096 and upper_key not in _SAFE_ENV_ALLOWLIST:
+            continue
+        filtered[key] = value
+    return filtered
+
+
+def cap_hook_output(text: str, max_chars: int = 4096, max_lines: int = 256) -> str:
+    """Cap hook stdout/stderr to prevent unbounded output in model context.
+
+    Args:
+        text: Raw output string.
+        max_chars: Maximum total characters to retain.
+        max_lines: Maximum number of lines to retain.
+
+    Returns:
+        Capped output with a truncation marker if trimmed.
+    """
+    if not text:
+        return text
+    lines = text.splitlines()
+    if len(lines) > max_lines:
+        lines = lines[:max_lines]
+        truncated = True
+    else:
+        truncated = False
+    result = "\n".join(lines)
+    if len(result) > max_chars:
+        result = result[:max_chars]
+        truncated = True
+    if truncated:
+        result += "\n... [output truncated]"
+    return result