htmlgraph 0.24.1__py3-none-any.whl → 0.25.0__py3-none-any.whl

htmlgraph/hooks/bootstrap.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Bootstrap utilities for hook scripts.
+
+Centralizes environment setup and project directory resolution used by all hooks.
+Handles both development (src/python) and installed (package) modes.
+"""
+
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def resolve_project_dir(cwd: str | None = None) -> str:
+    """Resolve the project directory with sensible fallbacks.
+
+    Hierarchy:
+    1. CLAUDE_PROJECT_DIR environment variable (set by Claude Code)
+    2. Git repository root (via git rev-parse --show-toplevel)
+    3. Current working directory (or provided cwd)
+
+    This supports running hooks in multiple contexts:
+    - Within a Claude Code session
+    - In git repositories
+    - In arbitrary directories
+
+    Args:
+        cwd: Starting directory for git search. Defaults to os.getcwd().
+
+    Returns:
+        Absolute path to the project directory.
+
+    Raises:
+        No exceptions - always returns a valid path.
+    """
+    # First priority: Claude's explicit project directory
+    env_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if env_dir:
+        return env_dir
+
+    # Second priority: Git repository root
+    start_dir = cwd or os.getcwd()
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            cwd=start_dir,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        # Git not available or not a repo - continue to fallback
+        pass
+
+    # Final fallback: current working directory
+    return start_dir
+
+
+def bootstrap_pythonpath(project_dir: str) -> None:
+    """Bootstrap Python path for htmlgraph imports.
+
+    Handles two common deployment modes:
+    1. Development: Running inside htmlgraph repository (src/python exists)
+    2. Installed: Running where htmlgraph is installed as a package (do nothing)
+
+    This allows hooks to work correctly whether htmlgraph is:
+    - Being developed locally (add src/python to path)
+    - Installed in a virtual environment (already in path)
+    - Installed globally (already in path)
+
+    Args:
+        project_dir: Project directory from resolve_project_dir().
+
+    Returns:
+        None (modifies sys.path in-place).
+
+    Side Effects:
+        - Modifies sys.path to ensure htmlgraph is importable
+        - Adds .venv/lib/pythonX.Y/site-packages if virtual environment exists
+        - Adds src/python if in htmlgraph repository
+    """
+    project_path = Path(project_dir)
+
+    # First, try to use local virtual environment if it exists
+    venv = project_path / ".venv"
+    if venv.exists():
+        pyver = f"python{sys.version_info.major}.{sys.version_info.minor}"
+        candidates = [
+            venv / "lib" / pyver / "site-packages",  # macOS/Linux
+            venv / "Lib" / "site-packages",  # Windows
+        ]
+        for candidate in candidates:
+            if candidate.exists():
+                sys.path.insert(0, str(candidate))
+                break
+
+    # Then, add src/python if this is the htmlgraph repository itself
+    repo_src = project_path / "src" / "python"
+    if repo_src.exists():
+        sys.path.insert(0, str(repo_src))
+
+
+def get_graph_dir(cwd: str | None = None) -> Path:
+    """Get the .htmlgraph directory path, creating it if necessary.
+
+    The .htmlgraph directory is the root for all HtmlGraph tracking:
+    - .htmlgraph/sessions/ - Session HTML files
+    - .htmlgraph/features/ - Feature tracking
+    - .htmlgraph/events/ - Event JSON files
+    - .htmlgraph/htmlgraph.db - SQLite database
+
+    Args:
+        cwd: Starting directory for project resolution. Defaults to os.getcwd().
+
+    Returns:
+        Path to the .htmlgraph directory (guaranteed to exist).
+
+    Raises:
+        OSError: If directory creation fails (e.g., permission denied).
+    """
+    project_dir = resolve_project_dir(cwd)
+    graph_dir = Path(project_dir) / ".htmlgraph"
+    graph_dir.mkdir(parents=True, exist_ok=True)
+    return graph_dir
+
+
+def init_logger(name: str) -> logging.Logger:
+    """Initialize a logger with standardized configuration.
+
+    Sets up a logger for hook scripts with:
+    - Consistent format across all hooks
+    - basicConfig applied only once (subsequent calls are ignored)
+    - Named logger returned (can be used for filtering)
+
+    Format: "[TIMESTAMP] [LEVEL] [logger_name] message"
+
+    Args:
+        name: Logger name (typically __name__ from calling module).
+
+    Returns:
+        logging.Logger instance configured and ready to use.
+
+    Example:
+        ```python
+        logger = init_logger(__name__)
+        logger.info("Hook started")
+        logger.error("Something went wrong")
+        ```
+    """
+    # Configure basicConfig only once (subsequent calls are no-ops)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # Return named logger for this module
+    return logging.getLogger(name)
+
+
+__all__ = [
+    "resolve_project_dir",
+    "bootstrap_pythonpath",
+    "get_graph_dir",
+    "init_logger",
+]

htmlgraph/hooks/context.py

@@ -0,0 +1,271 @@
+"""
+Hook Execution Context Manager.
+
+Manages hook execution context including lazy-loading of expensive resources
+(database, session manager) to minimize initialization overhead.
+
+This module provides a centralized context object that hooks can use to:
+- Access the graph directory and project directory
+- Retrieve session information
+- Access the database for event recording
+- Perform unified logging
+
+Key Design Principles:
+- Lazy-loading: Expensive resources (DB, SessionManager) are only loaded on first access
+- Resource cleanup: Context properly closes resources when done
+- Type safety: Full type hints for all public methods and properties
+- Error handling: Graceful degradation if resources fail to initialize
+"""
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HookContext:
+    """
+    Hook execution context with lazy-loaded resources.
+
+    Attributes:
+        project_dir: Absolute path to project root directory
+        graph_dir: Path to .htmlgraph directory for tracking data
+        session_id: Unique session identifier for this execution
+        agent_id: Agent/tool that's executing (e.g., 'claude-code', 'codex')
+        hook_input: Raw hook input data from Claude Code
+        _session_manager: Cached SessionManager instance (lazy-loaded)
+        _database: Cached HtmlGraphDB instance (lazy-loaded)
+    """
+
+    project_dir: str
+    graph_dir: Path
+    session_id: str
+    agent_id: str
+    hook_input: dict
+    _session_manager: Any | None = field(default=None, repr=False)
+    _database: Any | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_input(cls, hook_input: dict) -> "HookContext":
+        """
+        Create HookContext from raw hook input.
+
+        Performs automatic environment resolution:
+        - Extracts session_id from hook_input
+        - Detects agent_id from environment or hook_input
+        - Resolves project directory via bootstrap
+        - Initializes graph directory
+
+        Args:
+            hook_input: Raw hook input dict from Claude Code hook system
+
+        Returns:
+            Initialized HookContext instance
+
+        Raises:
+            ImportError: If bootstrap module cannot be imported
+            OSError: If graph directory cannot be created
+
+        Example:
+            ```python
+            hook_input = {
+                'session_id': 'sess-abc123',
+                'type': 'pretooluse',
+                'tool_name': 'Edit',
+                ...
+            }
+            context = HookContext.from_input(hook_input)
+            logger.info(f"Session: {context.session_id}, Agent: {context.agent_id}")
+            ```
+        """
+        # Import bootstrap locally to avoid circular imports
+        from htmlgraph.hooks.bootstrap import (
+            get_graph_dir,
+            resolve_project_dir,
+        )
+
+        # Extract session ID from hook input
+        session_id = hook_input.get("session_id", "unknown")
+
+        # Detect agent ID (priority order)
+        # 1. Explicit agent_id in hook input
+        # 2. HTMLGRAPH_AGENT_ID environment variable
+        # 3. CLAUDE_AGENT_NICKNAME environment variable (Claude Code)
+        # 4. Default to 'unknown'
+        agent_id = (
+            hook_input.get("agent_id")
+            or os.environ.get("HTMLGRAPH_AGENT_ID")
+            or os.environ.get("CLAUDE_AGENT_NICKNAME", "unknown")
+        )
+
+        # Resolve project directory with fallbacks
+        project_dir = resolve_project_dir()
+
+        # Get or create graph directory
+        graph_dir = get_graph_dir(project_dir)
+
+        logger.info(
+            f"Initializing hook context: session={session_id}, "
+            f"agent={agent_id}, project={project_dir}"
+        )
+
+        return cls(
+            project_dir=project_dir,
+            graph_dir=graph_dir,
+            session_id=session_id,
+            agent_id=agent_id,
+            hook_input=hook_input,
+        )
+
+    @property
+    def session_manager(self) -> Any:
+        """
+        Lazy-load and cache SessionManager instance.
+
+        Importing SessionManager is expensive (thousands of file system operations
+        for graph initialization), so we defer until first access.
+
+        Returns:
+            SessionManager instance for session tracking and activity attribution
+
+        Raises:
+            ImportError: If SessionManager cannot be imported
+            Exception: If SessionManager initialization fails
+
+        Note:
+            SessionManager is cached after first access. Multiple accesses
+            return the same instance.
+        """
+        if self._session_manager is not None:
+            return self._session_manager
+
+        try:
+            from htmlgraph.session_manager import SessionManager
+
+            logger.debug(f"Loading SessionManager for {self.graph_dir}")
+            self._session_manager = SessionManager(graph_dir=self.graph_dir)
+            logger.info("SessionManager loaded successfully")
+            return self._session_manager
+        except ImportError as e:
+            logger.error(f"Failed to import SessionManager: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to initialize SessionManager: {e}")
+            raise
+
+    @property
+    def database(self) -> Any:
+        """
+        Lazy-load and cache HtmlGraphDB instance.
+
+        Database access is needed for event recording, but we defer initialization
+        until first access to minimize startup overhead.
+
+        Returns:
+            HtmlGraphDB instance for recording events and features
+
+        Raises:
+            ImportError: If HtmlGraphDB cannot be imported
+            Exception: If database connection fails
+
+        Note:
+            Database connection is cached after first access. Multiple accesses
+            return the same instance.
+        """
+        if self._database is not None:
+            return self._database
+
+        try:
+            from htmlgraph.db.schema import HtmlGraphDB
+
+            db_path = self.graph_dir / "htmlgraph.db"
+            logger.debug(f"Loading HtmlGraphDB at {db_path}")
+            self._database = HtmlGraphDB(str(db_path))
+            logger.info("HtmlGraphDB loaded successfully")
+            return self._database
+        except ImportError as e:
+            logger.error(f"Failed to import HtmlGraphDB: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to initialize HtmlGraphDB: {e}")
+            raise
+
+    def close(self) -> None:
+        """
+        Clean up and close all resources gracefully.
+
+        Closes database connections and session manager resources.
+        Safe to call multiple times (idempotent).
+
+        This should be called in a finally block to ensure cleanup:
+
+        Example:
+            ```python
+            context = HookContext.from_input(hook_input)
+            try:
+                # Use context
+                context.session_manager.track_activity(...)
+            finally:
+                context.close()  # Always cleanup
+            ```
+        """
+        # Close database if loaded
+        if self._database is not None:
+            try:
+                logger.debug("Closing database connection")
+                self._database.close()
+                self._database = None
+                logger.info("Database closed successfully")
+            except Exception as e:
+                logger.warning(f"Error closing database: {e}")
+
+        # Close session manager if loaded
+        if self._session_manager is not None:
+            try:
+                logger.debug("Closing session manager")
+                # SessionManager doesn't currently have a close method,
+                # but we keep this for future resource management
+                self._session_manager = None
+                logger.info("Session manager cleaned up")
+            except Exception as e:
+                logger.warning(f"Error closing session manager: {e}")
+
+    def log(self, level: str, message: str) -> None:
+        """
+        Unified logging for hooks.
+
+        Provides consistent logging across all hook modules with context
+        information (session_id, agent_id, project_dir).
+
+        Args:
+            level: Log level as string ('debug', 'info', 'warning', 'error', 'critical')
+            message: Message to log
+
+        Example:
+            ```python
+            context.log('info', 'Processing user query')
+            context.log('error', f'Failed to track activity: {error}')
+            ```
+        """
+        log_func = getattr(logger, level.lower(), logger.info)
+
+        # Prefix message with context for better debugging
+        context_msg = f"[{self.session_id[:8]}][{self.agent_id}] {message}"
+        log_func(context_msg)
+
+    def __enter__(self) -> "HookContext":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit with resource cleanup."""
+        self.close()
+
+
+__all__ = [
+    "HookContext",
+]