htmlgraph 0.20.1__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/file_watcher.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 File watcher for automatic graph reloading.
 
@@ -67,7 +71,7 @@ class GraphFileHandler(FileSystemEventHandler):
 
     def _trigger_reload(self) -> None:
         """Trigger a reload after debounce delay."""
-        print(f"[FileWatcher] Reloading collection: {self.collection}")
+        logger.info(f"[FileWatcher] Reloading collection: {self.collection}")
         self.reload_callback()
 
     def _debounced_reload(self) -> None:
@@ -87,7 +91,7 @@ class GraphFileHandler(FileSystemEventHandler):
         if not self._is_relevant_file(str(event.src_path)):
             return
 
-        print(
+        logger.debug(
             f"[FileWatcher] {self.collection}: File created - {Path(str(event.src_path)).name}"
         )
         self._debounced_reload()
@@ -101,7 +105,7 @@ class GraphFileHandler(FileSystemEventHandler):
         if not self._is_relevant_file(str(event.src_path)):
             return
 
-        print(
+        logger.debug(
             f"[FileWatcher] {self.collection}: File modified - {Path(str(event.src_path)).name}"
         )
         self._debounced_reload()
@@ -115,7 +119,7 @@ class GraphFileHandler(FileSystemEventHandler):
         if not self._is_relevant_file(str(event.src_path)):
             return
 
-        print(
+        logger.debug(
             f"[FileWatcher] {self.collection}: File deleted - {Path(str(event.src_path)).name}"
         )
         self._debounced_reload()
@@ -146,7 +150,7 @@ class GraphWatcher:
 
     def start(self) -> None:
         """Start watching for file changes."""
-        print(
+        logger.info(
             f"[FileWatcher] Starting file watcher for {len(self.collections)} collections..."
         )
 
@@ -160,7 +164,7 @@ class GraphWatcher:
                 def reload() -> None:
                     graph = self.get_graph_callback(coll)
                     count = graph.reload()
-                    print(f"[FileWatcher] Reloaded {count} nodes in {coll}")
+                    logger.info(f"[FileWatcher] Reloaded {count} nodes in {coll}")
 
                 return reload
 
@@ -173,11 +177,11 @@ class GraphWatcher:
             self.observer.schedule(handler, str(collection_dir), recursive=recursive)
 
         self.observer.start()
-        print(f"[FileWatcher] Watching {self.graph_dir} for changes...")
+        logger.info(f"[FileWatcher] Watching {self.graph_dir} for changes...")
 
     def stop(self) -> None:
         """Stop watching for file changes."""
-        print("[FileWatcher] Stopping file watcher...")
+        logger.info("[FileWatcher] Stopping file watcher...")
         self.observer.stop()
         self.observer.join()
 

htmlgraph/find_api.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 BeautifulSoup-style Find API for HtmlGraph.
 
@@ -22,7 +24,6 @@ Example:
     nodes = graph.find_all(properties__effort__gt=8)
 """
 
-from __future__ import annotations
 
 import re
 from collections.abc import Callable

htmlgraph/git_events.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Git event logging for HtmlGraph.
 
@@ -10,7 +12,6 @@ Design goals:
 - Analytics-friendly: schema compatible with EventRecord/AnalyticsIndex
 """
 
-from __future__ import annotations
 
 import os
 import re
@@ -168,9 +169,19 @@ def parse_feature_refs(message: str) -> list[str]:
     Parse feature IDs from commit message.
 
     Looks for patterns like:
-    - Implements: feature-xyz
+    - Implements: feat-xyz
     - Fixes: bug-abc
-    - feature-xyz
+    - [feat-123abc]
+    - feat-xyz
+
+    Supports HtmlGraph ID formats:
+    - feat-XXXXXXXX (features)
+    - feature-XXXXXXXX (legacy features)
+    - bug-XXXXXXXX (bugs)
+    - spk-XXXXXXXX (spikes)
+    - spike-XXXXXXXX (legacy spikes)
+    - chr-XXXXXXXX (chores)
+    - trk-XXXXXXXX (tracks)
 
     Args:
         message: Commit message
@@ -180,14 +191,21 @@ def parse_feature_refs(message: str) -> list[str]:
     """
     features = []
 
-    # Pattern: Implements: feature-xyz
-    pattern1 = r"(?:Implements|Fixes|Closes|Refs):\s*(feature-[\w-]+|bug-[\w-]+)"
+    # All HtmlGraph ID prefixes (current + legacy)
+    id_prefixes = r"(?:feat|feature|bug|spk|spike|chr|chore|trk|track|todo)"
+
+    # Pattern 1: Explicit tags (Implements: feat-xyz)
+    pattern1 = rf"(?:Implements|Fixes|Closes|Refs):\s*({id_prefixes}-[\w-]+)"
     features.extend(re.findall(pattern1, message, re.IGNORECASE))
 
-    # Pattern: feature-xyz (anywhere in message)
-    pattern2 = r"\b(feature-[\w-]+|bug-[\w-]+)\b"
+    # Pattern 2: Square brackets [feat-xyz] (common in commit messages)
+    pattern2 = rf"\[({id_prefixes}-[\w-]+)\]"
     features.extend(re.findall(pattern2, message, re.IGNORECASE))
 
+    # Pattern 3: Anywhere in message as word boundary
+    pattern3 = rf"\b({id_prefixes}-[\w-]+)\b"
+    features.extend(re.findall(pattern3, message, re.IGNORECASE))
+
     # Remove duplicates while preserving order
     seen = set()
     unique_features = []
@@ -260,7 +278,10 @@ def _append_event(
         p.parent.mkdir(parents=True, exist_ok=True)
         with p.open("a", encoding="utf-8") as f:
             f.write(
-                json.dumps(record.to_json(), ensure_ascii=False, default=str) + "\n"
+                json.dumps(
+                    record.model_dump(mode="json"), ensure_ascii=False, default=str
+                )
+                + "\n"
             )
         return
 
@@ -288,7 +309,44 @@ def _determine_context(graph_dir: Path, commit_message: str | None = None) -> di
         if f and f not in all_features:
             all_features.append(f)
 
-    session = get_active_session(graph_dir)
+    # Try to find the right session based on feature IDs in commit message
+    # This handles multi-agent scenarios where multiple sessions are active
+    session = None
+    if message_features:
+        # If commit mentions specific features, find the session working on them
+        manager = _get_session_manager(graph_dir)
+        if manager:
+            try:
+                # Try to find a session that has any of the message features as active
+                for feature_id in message_features:
+                    # Get the feature to check which agent is working on it
+                    try:
+                        # Try features graph first
+                        feature = manager.features_graph.get(feature_id)
+                        if not feature:
+                            # Try bugs graph
+                            feature = manager.bugs_graph.get(feature_id)
+
+                        if (
+                            feature
+                            and hasattr(feature, "agent_assigned")
+                            and feature.agent_assigned
+                        ):
+                            # Find active session for this agent
+                            session = manager.get_active_session(
+                                agent=feature.agent_assigned
+                            )
+                            if session:
+                                break
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+
+    # Fallback to any active session if we couldn't match by feature
+    if not session:
+        session = get_active_session(graph_dir)
+
     if session:
         return {
             "session_id": session.id,

htmlgraph/hooks/.htmlgraph/.session-warning-state.json

@@ -0,0 +1,6 @@
+{
+  "dismissed_at": null,
+  "dismissed_by": null,
+  "session_id": null,
+  "show_count": 121
+}

htmlgraph/hooks/.htmlgraph/agents.json

@@ -0,0 +1,72 @@
+{
+  "version": "1.0",
+  "updated": "2026-01-10T08:55:56.503507",
+  "agents": {
+    "claude": {
+      "id": "claude",
+      "name": "Claude",
+      "capabilities": [
+        "python",
+        "javascript",
+        "typescript",
+        "html",
+        "css",
+        "code-review",
+        "testing",
+        "documentation",
+        "debugging",
+        "refactoring",
+        "architecture",
+        "api-design"
+      ],
+      "max_parallel_tasks": 3,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high",
+        "very-high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "gemini": {
+      "id": "gemini",
+      "name": "Gemini",
+      "capabilities": [
+        "python",
+        "data-analysis",
+        "documentation",
+        "testing",
+        "code-review",
+        "javascript"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "codex": {
+      "id": "codex",
+      "name": "Codex",
+      "capabilities": [
+        "python",
+        "javascript",
+        "debugging",
+        "testing",
+        "code-generation",
+        "documentation"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium"
+      ],
+      "active": true,
+      "metadata": {}
+    }
+  }
+}

htmlgraph/hooks/__init__.py

@@ -16,6 +16,11 @@ from pathlib import Path
 
 from htmlgraph.hooks.posttooluse import posttooluse_hook
 from htmlgraph.hooks.pretooluse import pretooluse_hook
+from htmlgraph.hooks.state_manager import (
+    DriftQueueManager,
+    ParentActivityTracker,
+    UserQueryEventTracker,
+)
 
 # Directory containing hook scripts
 HOOKS_DIR = Path(__file__).parent
@@ -32,6 +37,9 @@ AVAILABLE_HOOKS = [
 __all__ = [
     "pretooluse_hook",
     "posttooluse_hook",
+    "ParentActivityTracker",
+    "UserQueryEventTracker",
+    "DriftQueueManager",
     "AVAILABLE_HOOKS",
     "HOOKS_DIR",
 ]

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",
+]