htmlgraph 0.24.2__py3-none-any.whl → 0.26.1__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/cigs_pretool_enforcer.py

@@ -87,7 +87,7 @@ class CIGSPreToolEnforcer:
 
         return graph_dir
 
-    def enforce(self, tool: str, params: dict) -> dict[str, Any]:
+    def enforce(self, tool: str, params: dict[str, Any]) -> dict[str, Any]:
         """
         Enforce CIGS delegation rules with escalating guidance.
 
@@ -223,7 +223,7 @@ class CIGSPreToolEnforcer:
             }
         }
 
-    def _is_sdk_operation(self, tool: str, params: dict) -> bool:
+    def _is_sdk_operation(self, tool: str, params: dict[str, Any]) -> bool:
         """Check if operation is an SDK operation (always allowed)."""
         if tool != "Bash":
             return False

htmlgraph/hooks/concurrent_sessions.py

@@ -0,0 +1,208 @@
+"""
+Concurrent Session Detection and Formatting.
+
+Provides utilities to detect other active sessions and format them
+for injection into the orchestrator's context at session start.
+"""
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from htmlgraph.db.schema import HtmlGraphDB
+
+
+def get_concurrent_sessions(
+    db: HtmlGraphDB,
+    current_session_id: str,
+    minutes: int = 30,
+) -> list[dict[str, Any]]:
+    """
+    Get other sessions that are currently active.
+
+    Args:
+        db: Database connection
+        current_session_id: Current session to exclude
+        minutes: Look back window for activity
+
+    Returns:
+        List of concurrent session dicts with id, agent_id, last_user_query, etc.
+    """
+    if not db.connection:
+        db.connect()
+
+    try:
+        cursor = db.connection.cursor()  # type: ignore[union-attr]
+        # Use datetime format that matches database (without timezone)
+        cutoff = (datetime.now(timezone.utc) - timedelta(minutes=minutes)).strftime(
+            "%Y-%m-%d %H:%M:%S"
+        )
+
+        cursor.execute(
+            """
+            SELECT
+                session_id as id,
+                agent_assigned as agent_id,
+                created_at,
+                status,
+                (SELECT input_summary FROM agent_events
+                 WHERE session_id = sessions.session_id
+                 ORDER BY timestamp DESC LIMIT 1) as last_user_query,
+                (SELECT timestamp FROM agent_events
+                 WHERE session_id = sessions.session_id
+                 ORDER BY timestamp DESC LIMIT 1) as last_user_query_at
+            FROM sessions
+            WHERE status = 'active'
+              AND session_id != ?
+              AND created_at > ?
+            ORDER BY created_at DESC
+            """,
+            (current_session_id, cutoff),
+        )
+
+        rows = cursor.fetchall()
+        return [dict(row) for row in rows]
+    except Exception:  # pragma: no cover
+        # Gracefully handle database errors
+        return []
+
+
+def format_concurrent_sessions_markdown(sessions: list[dict[str, Any]]) -> str:
+    """
+    Format concurrent sessions as markdown for context injection.
+
+    Args:
+        sessions: List of session dicts from get_concurrent_sessions
+
+    Returns:
+        Markdown formatted string for system prompt injection
+    """
+    if not sessions:
+        return ""
+
+    lines = ["## Concurrent Sessions (Active Now)", ""]
+
+    for session in sessions:
+        session_id = session.get("id", "unknown")
+        session_id = session_id[:12] if len(session_id) > 12 else session_id
+        agent = session.get("agent_id", "unknown")
+        query = session.get("last_user_query", "No recent query")
+        last_active = session.get("last_user_query_at")
+
+        # Calculate time ago
+        time_ago = "unknown"
+        if last_active:
+            try:
+                last_dt = datetime.fromisoformat(
+                    last_active.replace("Z", "+00:00")
+                    if isinstance(last_active, str)
+                    else last_active
+                )
+                delta = datetime.now(timezone.utc) - last_dt
+                if delta.total_seconds() < 60:
+                    time_ago = "just now"
+                elif delta.total_seconds() < 3600:
+                    time_ago = f"{int(delta.total_seconds() // 60)} min ago"
+                else:
+                    time_ago = f"{int(delta.total_seconds() // 3600)} hours ago"
+            except (ValueError, TypeError, AttributeError):
+                time_ago = "unknown"
+
+        # Truncate query for display
+        query_display = (
+            query[:50] + "..." if query and len(query) > 50 else (query or "Unknown")
+        )
+
+        lines.append(f'- **{session_id}** ({agent}): "{query_display}" - {time_ago}')
+
+    lines.append("")
+    lines.append("*Coordinate with concurrent sessions to avoid duplicate work.*")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def get_recent_completed_sessions(
+    db: HtmlGraphDB,
+    hours: int = 24,
+    limit: int = 5,
+) -> list[dict[str, Any]]:
+    """
+    Get recently completed sessions for handoff context.
+
+    Args:
+        db: Database connection
+        hours: Look back window
+        limit: Maximum sessions to return
+
+    Returns:
+        List of recently completed session dicts
+    """
+    if not db.connection:
+        db.connect()
+
+    try:
+        cursor = db.connection.cursor()  # type: ignore[union-attr]
+        # Use datetime format that matches database (without timezone)
+        cutoff = (datetime.now(timezone.utc) - timedelta(hours=hours)).strftime(
+            "%Y-%m-%d %H:%M:%S"
+        )
+        cursor.execute(
+            """
+            SELECT session_id as id, agent_assigned as agent_id, created_at as started_at,
+                   completed_at, total_events,
+                   (SELECT input_summary FROM agent_events
+                    WHERE session_id = sessions.session_id
+                    ORDER BY timestamp DESC LIMIT 1) as last_user_query
+            FROM sessions
+            WHERE status = 'completed'
+              AND completed_at > ?
+            ORDER BY completed_at DESC
+            LIMIT ?
+            """,
+            (cutoff, limit),
+        )
+        rows = cursor.fetchall()
+        return [dict(row) for row in rows]
+    except Exception:  # pragma: no cover
+        # Gracefully handle database errors
+        return []
+
+
+def format_recent_work_markdown(sessions: list[dict[str, Any]]) -> str:
+    """
+    Format recently completed sessions as markdown.
+
+    Args:
+        sessions: List of completed session dicts
+
+    Returns:
+        Markdown formatted string
+    """
+    if not sessions:
+        return ""
+
+    lines = ["## Recent Work (Last 24 Hours)", ""]
+
+    for session in sessions:
+        session_id = session.get("id", "unknown")
+        session_id = session_id[:12] if len(session_id) > 12 else session_id
+        query = session.get("last_user_query", "No query recorded")
+        total_events = session.get("total_events") or 0
+
+        query_display = (
+            query[:60] + "..." if query and len(query) > 60 else (query or "Unknown")
+        )
+
+        lines.append(f"- `{session_id}`: {query_display} ({total_events} events)")
+
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+__all__ = [
+    "get_concurrent_sessions",
+    "format_concurrent_sessions_markdown",
+    "get_recent_completed_sessions",
+    "format_recent_work_markdown",
+]