htmlgraph 0.26.21__py3-none-any.whl → 0.26.23__py3-none-any.whl

htmlgraph/decorators.py

@@ -0,0 +1,317 @@
+"""Decorators for function enhancement and cross-cutting concerns.
+
+This module provides decorators for common patterns like retry logic with
+exponential backoff, caching, timing, and error handling.
+"""
+
+import functools
+import logging
+import random
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class RetryError(Exception):
+    """Raised when a function exhausts all retry attempts."""
+
+    def __init__(
+        self,
+        function_name: str,
+        attempts: int,
+        last_exception: Exception,
+    ):
+        self.function_name = function_name
+        self.attempts = attempts
+        self.last_exception = last_exception
+        super().__init__(
+            f"Function '{function_name}' failed after {attempts} attempts. "
+            f"Last error: {last_exception}"
+        )
+
+
+def retry(
+    max_attempts: int = 3,
+    initial_delay: float = 1.0,
+    max_delay: float = 60.0,
+    exponential_base: float = 2.0,
+    jitter: bool = True,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+    on_retry: Callable[[int, Exception, float], None] | None = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator adding retry logic with exponential backoff to any function.
+
+    Implements exponential backoff with optional jitter to gracefully handle
+    transient failures. Useful for I/O operations, API calls, and distributed
+    system interactions.
+
+    Args:
+        max_attempts: Maximum number of attempts (default: 3). Must be >= 1.
+        initial_delay: Initial delay in seconds before first retry (default: 1.0).
+            Must be >= 0.
+        max_delay: Maximum delay in seconds between retries (default: 60.0).
+            Caps the exponential backoff. Must be >= initial_delay.
+        exponential_base: Base for exponential backoff calculation (default: 2.0).
+            delay = min(initial_delay * (base ** attempt_number), max_delay)
+        jitter: Whether to add random jitter to delays (default: True).
+            Helps prevent thundering herd problem in distributed systems.
+        exceptions: Tuple of exception types to catch and retry on
+            (default: (Exception,)). Other exceptions propagate immediately.
+        on_retry: Optional callback invoked on each retry with signature:
+            on_retry(attempt_number, exception, delay_seconds).
+            Useful for logging, metrics, or custom backoff strategies.
+
+    Returns:
+        Decorated function that retries on specified exceptions.
+
+    Raises:
+        RetryError: If all retry attempts are exhausted.
+        Other exceptions: If exception type is not in the retry list.
+
+    Examples:
+        Basic retry with default parameters:
+        >>> @retry()
+        ... def unstable_api_call():
+        ...     response = requests.get('https://api.example.com/data')
+        ...     response.raise_for_status()
+        ...     return response.json()
+
+        Retry with custom parameters:
+        >>> @retry(
+        ...     max_attempts=5,
+        ...     initial_delay=0.5,
+        ...     max_delay=30.0,
+        ...     exponential_base=1.5,
+        ...     exceptions=(ConnectionError, TimeoutError),
+        ... )
+        ... def fetch_with_timeout():
+        ...     return expensive_io_operation()
+
+        With custom retry callback for logging:
+        >>> def log_retry(attempt, exc, delay):
+        ...     logger.warning(
+        ...         f"Retry attempt {attempt} after {delay}s: {exc}"
+        ...     )
+        >>> @retry(
+        ...     max_attempts=3,
+        ...     on_retry=log_retry,
+        ...     exceptions=(IOError,),
+        ... )
+        ... def read_file(path):
+        ...     with open(path) as f:
+        ...         return f.read()
+
+        Retry only specific exceptions (fail fast for others):
+        >>> @retry(
+        ...     max_attempts=3,
+        ...     exceptions=(ConnectionError, TimeoutError),
+        ... )
+        ... def resilient_request(url):
+        ...     # Will retry on connection errors but fail immediately on 404
+        ...     return requests.get(url, timeout=5).json()
+
+        Using with async functions:
+        >>> import asyncio
+        >>> @retry(max_attempts=3, initial_delay=0.1)
+        ... async def async_api_call():
+        ...     async with aiohttp.ClientSession() as session:
+        ...         async with session.get('https://api.example.com') as resp:
+        ...             return await resp.json()
+        >>> asyncio.run(async_api_call())
+
+    Backoff Calculation:
+        The delay before retry N is calculated as:
+        - exponential: initial_delay * (exponential_base ** (attempt - 1))
+        - capped: min(exponential, max_delay)
+        - jittered: delay * (0.5 + random(0.0, 1.0)) if jitter=True
+
+        Example with exponential_base=2.0, initial_delay=1.0, max_delay=60.0:
+        - Attempt 1 fails, retry after: 1s
+        - Attempt 2 fails, retry after: 2s
+        - Attempt 3 fails, retry after: 4s
+        - Attempt 4 fails, retry after: 8s
+        - Attempt 5 fails, retry after: 16s
+        - Attempt 6 fails, retry after: 32s
+        - Attempt 7 fails, raise RetryError (max_attempts=3 means 3 total attempts)
+
+    Notes:
+        - If max_attempts=1, no retries occur (function runs once)
+        - Jitter is uniformly distributed in range [0.5 * delay, 1.5 * delay]
+        - Callbacks (on_retry) are invoked BEFORE sleeping, not after
+        - Thread-safe but not async-safe without adaptation
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+    if initial_delay < 0:
+        raise ValueError("initial_delay must be >= 0")
+    if max_delay < initial_delay:
+        raise ValueError("max_delay must be >= initial_delay")
+    if exponential_base <= 0:
+        raise ValueError("exponential_base must be > 0")
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            last_exception: Exception | None = None
+
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+
+                    if attempt == max_attempts:
+                        # Last attempt failed, raise RetryError
+                        raise RetryError(
+                            function_name=func.__name__,
+                            attempts=max_attempts,
+                            last_exception=e,
+                        ) from e
+
+                    # Calculate backoff with exponential growth and jitter
+                    exponential_delay = initial_delay * (
+                        exponential_base ** (attempt - 1)
+                    )
+                    delay = min(exponential_delay, max_delay)
+
+                    if jitter:
+                        # Add jitter: multiply by random value in [0.5, 1.5]
+                        delay *= 0.5 + random.random()
+
+                    # Invoke callback before sleeping
+                    if on_retry is not None:
+                        on_retry(attempt, e, delay)
+                    else:
+                        logger.debug(
+                            f"Retry attempt {attempt}/{max_attempts} for "
+                            f"{func.__name__} after {delay:.2f}s: {e}"
+                        )
+
+                    time.sleep(delay)
+
+            # This should never be reached, but satisfy type checker
+            assert last_exception is not None
+            raise RetryError(
+                function_name=func.__name__,
+                attempts=max_attempts,
+                last_exception=last_exception,
+            )
+
+        return wrapper
+
+    return decorator
+
+
+def retry_async(
+    max_attempts: int = 3,
+    initial_delay: float = 1.0,
+    max_delay: float = 60.0,
+    exponential_base: float = 2.0,
+    jitter: bool = True,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+    on_retry: Callable[[int, Exception, float], None] | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Async version of retry decorator with exponential backoff.
+
+    Identical to retry() but uses asyncio.sleep instead of time.sleep,
+    allowing it to be used with async/await functions without blocking.
+
+    Args:
+        max_attempts: Maximum number of attempts (default: 3). Must be >= 1.
+        initial_delay: Initial delay in seconds before first retry (default: 1.0).
+        max_delay: Maximum delay in seconds between retries (default: 60.0).
+        exponential_base: Base for exponential backoff (default: 2.0).
+        jitter: Whether to add random jitter to delays (default: True).
+        exceptions: Tuple of exception types to catch and retry on.
+        on_retry: Optional callback invoked on each retry.
+
+    Returns:
+        Decorated async function that retries on specified exceptions.
+
+    Raises:
+        RetryError: If all retry attempts are exhausted.
+
+    Examples:
+        >>> import asyncio
+        >>> @retry_async(max_attempts=3)
+        ... async def fetch_data():
+        ...     async with aiohttp.ClientSession() as session:
+        ...         async with session.get('https://api.example.com') as resp:
+        ...             return await resp.json()
+
+        >>> @retry_async(
+        ...     max_attempts=5,
+        ...     initial_delay=0.1,
+        ...     exceptions=(asyncio.TimeoutError, ConnectionError),
+        ... )
+        ... async def resilient_query():
+        ...     return await db.query("SELECT * FROM users")
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+    if initial_delay < 0:
+        raise ValueError("initial_delay must be >= 0")
+    if max_delay < initial_delay:
+        raise ValueError("max_delay must be >= initial_delay")
+    if exponential_base <= 0:
+        raise ValueError("exponential_base must be > 0")
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            import asyncio
+
+            last_exception: Exception | None = None
+
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    return await func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+
+                    if attempt == max_attempts:
+                        raise RetryError(
+                            function_name=func.__name__,
+                            attempts=max_attempts,
+                            last_exception=e,
+                        ) from e
+
+                    exponential_delay = initial_delay * (
+                        exponential_base ** (attempt - 1)
+                    )
+                    delay = min(exponential_delay, max_delay)
+
+                    if jitter:
+                        delay *= 0.5 + random.random()
+
+                    if on_retry is not None:
+                        on_retry(attempt, e, delay)
+                    else:
+                        logger.debug(
+                            f"Retry attempt {attempt}/{max_attempts} for "
+                            f"{func.__name__} after {delay:.2f}s: {e}"
+                        )
+
+                    await asyncio.sleep(delay)
+
+            assert last_exception is not None
+            raise RetryError(
+                function_name=func.__name__,
+                attempts=max_attempts,
+                last_exception=last_exception,
+            )
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = [
+    "retry",
+    "retry_async",
+    "RetryError",
+]

htmlgraph/hooks/subagent_stop.py

@@ -204,6 +204,52 @@ def get_parent_event_start_time(db_path: str, parent_event_id: str) -> str | Non
         return None
 
 
+def get_parent_event_from_db(db_path: str) -> str | None:
+    """
+    Query database for the most recent task_delegation event.
+
+    Used when HTMLGRAPH_PARENT_EVENT environment variable is not available
+    (due to inter-process communication limitations).
+
+    Args:
+        db_path: Path to SQLite database
+
+    Returns:
+        Parent event ID (evt-XXXXX) or None if not found
+    """
+    try:
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        # Query for the most recent task_delegation with status='started'
+        # This is the task that spawned the current subagent
+        query = """
+            SELECT event_id FROM agent_events
+            WHERE event_type = 'task_delegation'
+            AND status = 'started'
+            ORDER BY timestamp DESC
+            LIMIT 1
+        """
+
+        cursor.execute(query)
+        result = cursor.fetchone()
+        conn.close()
+
+        if result:
+            parent_event_id: str = result[0]
+            logger.debug(
+                f"Found parent task_delegation from database: {parent_event_id}"
+            )
+            return parent_event_id
+
+        logger.debug("No active task_delegation found in database")
+        return None
+
+    except Exception as e:
+        logger.warning(f"Error querying for parent event: {e}")
+        return None
+
+
 def handle_subagent_stop(hook_input: dict[str, Any]) -> dict[str, Any]:
     """
     Handle SubagentStop hook event.
@@ -222,14 +268,13 @@ def handle_subagent_stop(hook_input: dict[str, Any]) -> dict[str, Any]:
     Returns:
         Response: {"continue": True} with optional context
     """
-    # Get parent event ID from environment
+    # Try to get parent event ID from environment (set by PreToolUse hook)
     parent_event_id = get_parent_event_id()
 
-    if not parent_event_id:
-        logger.debug("No parent event ID found, skipping subagent stop tracking")
-        return {"continue": True}
-
-    # Get project directory and database path
+    # If not available in environment, query database
+    # (environment variables may not be inherited across subagent process boundary)
+    # Get project directory and database path (reuse for both env and db lookup)
+    db_path = None
     try:
         from htmlgraph.config import get_database_path
 
@@ -244,6 +289,20 @@ def handle_subagent_stop(hook_input: dict[str, Any]) -> dict[str, Any]:
         logger.warning(f"Error resolving database path: {e}")
         return {"continue": True}
 
+    # If parent event ID not in environment, query database
+    if not parent_event_id:
+        logger.debug("Parent event ID not in environment, querying database...")
+        try:
+            parent_event_id = get_parent_event_from_db(db_path)
+        except Exception as e:
+            logger.debug(f"Could not query database for parent event: {e}")
+
+    if not parent_event_id:
+        logger.debug(
+            "No parent event ID found (env or db), skipping subagent stop tracking"
+        )
+        return {"continue": True}
+
     # Get parent event start time
     parent_start_time = get_parent_event_start_time(db_path, parent_event_id)
     if not parent_start_time:

htmlgraph/operations/bootstrap.py

@@ -0,0 +1,288 @@
+"""HtmlGraph bootstrap operations.
+
+One-command setup to go from installation to first value in under 60 seconds.
+This module provides functions for bootstrapping a project with HtmlGraph.
+
+The bootstrap process includes:
+1. Auto-detecting project type (Python, Node, etc.)
+2. Creating .htmlgraph directory structure
+3. Initializing database with schema
+4. Installing Claude Code plugin hooks automatically
+5. Printing next steps for the user
+
+This is designed for simplicity and speed - the minimal viable setup.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.cli.models import BootstrapConfig
+
+
+def detect_project_type(project_dir: Path) -> str:
+    """
+    Auto-detect project type from files in directory.
+
+    Args:
+        project_dir: Project directory to inspect
+
+    Returns:
+        Detected project type: "python", "node", "multi", or "unknown"
+    """
+    # Check for Python project markers
+    has_python = any(
+        [
+            (project_dir / "pyproject.toml").exists(),
+            (project_dir / "setup.py").exists(),
+            (project_dir / "requirements.txt").exists(),
+            (project_dir / "Pipfile").exists(),
+        ]
+    )
+
+    # Check for Node project markers
+    has_node = (project_dir / "package.json").exists()
+
+    # Determine project type
+    if has_python and has_node:
+        return "multi"
+    elif has_python:
+        return "python"
+    elif has_node:
+        return "node"
+    else:
+        return "unknown"
+
+
+def create_gitignore_template() -> str:
+    """
+    Create .gitignore template content for .htmlgraph directory.
+
+    Returns:
+        Gitignore template content
+    """
+    return """# HtmlGraph cache and regenerable files
+.htmlgraph/htmlgraph.db
+.htmlgraph/sessions/*.jsonl
+.htmlgraph/events/*.jsonl
+.htmlgraph/parent-activity.json
+.htmlgraph/logs/
+"""
+
+
+def check_already_initialized(project_dir: Path) -> bool:
+    """
+    Check if project is already initialized with HtmlGraph.
+
+    Args:
+        project_dir: Project directory to check
+
+    Returns:
+        True if already initialized, False otherwise
+    """
+    graph_dir = project_dir / ".htmlgraph"
+    return graph_dir.exists()
+
+
+def create_bootstrap_structure(project_dir: Path) -> dict[str, list[str]]:
+    """
+    Create minimal .htmlgraph directory structure for bootstrap.
+
+    Args:
+        project_dir: Project directory
+
+    Returns:
+        Dictionary with lists of created directories and files
+    """
+    graph_dir = project_dir / ".htmlgraph"
+    created_dirs: list[str] = []
+    created_files: list[str] = []
+
+    # Create main .htmlgraph directory
+    if not graph_dir.exists():
+        graph_dir.mkdir(parents=True)
+        created_dirs.append(str(graph_dir))
+
+    # Create subdirectories
+    subdirs = [
+        "sessions",
+        "features",
+        "spikes",
+        "tracks",
+        "events",
+        "logs",
+        "logs/errors",
+    ]
+
+    for subdir in subdirs:
+        subdir_path = graph_dir / subdir
+        if not subdir_path.exists():
+            subdir_path.mkdir(parents=True)
+            created_dirs.append(str(subdir_path))
+
+    # Create .gitignore in .htmlgraph
+    gitignore = graph_dir / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text(create_gitignore_template())
+        created_files.append(str(gitignore))
+
+    # Create config.json
+    config_file = graph_dir / "config.json"
+    if not config_file.exists():
+        config_data = {
+            "bootstrapped": True,
+            "version": "1.0",
+        }
+        config_file.write_text(json.dumps(config_data, indent=2) + "\n")
+        created_files.append(str(config_file))
+
+    return {"directories": created_dirs, "files": created_files}
+
+
+def initialize_database(graph_dir: Path) -> str:
+    """
+    Initialize HtmlGraph database with schema.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+
+    Returns:
+        Path to created database file
+    """
+    from htmlgraph.db.schema import HtmlGraphDB
+
+    db_path = graph_dir / "htmlgraph.db"
+
+    # Create database using HtmlGraphDB (auto-creates tables)
+    db = HtmlGraphDB(db_path=str(db_path))
+    db.disconnect()
+
+    return str(db_path)
+
+
+def check_claude_code_available() -> bool:
+    """
+    Check if Claude Code CLI is available.
+
+    Returns:
+        True if claude command is available, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            ["claude", "--version"],
+            capture_output=True,
+            check=False,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+def get_next_steps(
+    project_type: str, has_claude: bool, plugin_installed: bool
+) -> list[str]:
+    """
+    Generate next steps message based on project state.
+
+    Args:
+        project_type: Detected project type
+        has_claude: Whether Claude Code CLI is available
+        plugin_installed: Whether plugin hooks were installed
+
+    Returns:
+        List of next step messages
+    """
+    steps = []
+
+    if has_claude:
+        if plugin_installed:
+            steps.append("1. Use Claude Code: Run 'claude --dev' in this project")
+        else:
+            steps.append(
+                "1. Install HtmlGraph plugin: Run 'claude plugin install htmlgraph'"
+            )
+            steps.append("2. Use Claude Code: Run 'claude --dev' in this project")
+    else:
+        steps.append(
+            "1. Install Claude Code CLI: Visit https://code.claude.com/docs/installation"
+        )
+        steps.append(
+            "2. Install HtmlGraph plugin: Run 'claude plugin install htmlgraph'"
+        )
+        steps.append("3. Use Claude Code: Run 'claude --dev' in this project")
+
+    steps.append(
+        f"{len(steps) + 1}. Track work: Create features with 'htmlgraph feature create \"Title\"'"
+    )
+    steps.append(f"{len(steps) + 1}. View progress: Run 'htmlgraph status'")
+    steps.append(
+        f"{len(steps) + 1}. See what Claude did: Run 'htmlgraph serve' and open http://localhost:8080"
+    )
+
+    return steps
+
+
+def bootstrap_htmlgraph(config: BootstrapConfig) -> dict[str, Any]:
+    """
+    Bootstrap HtmlGraph in a project directory.
+
+    This is the main entry point for the bootstrap command.
+
+    Args:
+        config: BootstrapConfig with bootstrap settings
+
+    Returns:
+        Dictionary with bootstrap results
+    """
+    project_dir = Path(config.project_path).resolve()
+
+    # Check if already initialized
+    if check_already_initialized(project_dir):
+        # Ask user if they want to overwrite
+        print(f"\n⚠️  HtmlGraph already initialized in {project_dir}")
+        response = input("Do you want to reinitialize? (y/N): ").strip().lower()
+        if response not in ["y", "yes"]:
+            return {
+                "success": False,
+                "message": "Bootstrap cancelled - already initialized",
+            }
+
+    # Detect project type
+    project_type = detect_project_type(project_dir)
+
+    # Create directory structure
+    created = create_bootstrap_structure(project_dir)
+    graph_dir = project_dir / ".htmlgraph"
+
+    # Initialize database
+    db_path = initialize_database(graph_dir)
+    created["files"].append(db_path)
+
+    # Check for Claude Code
+    has_claude = check_claude_code_available()
+
+    # Check if plugin is already available (skip installation check for now)
+    plugin_installed = False
+    if not config.no_plugins and has_claude:
+        # We'll consider it "installed" if hooks can be configured
+        # The actual plugin installation happens via marketplace
+        plugin_installed = True
+
+    # Generate next steps
+    next_steps = get_next_steps(project_type, has_claude, plugin_installed)
+
+    return {
+        "success": True,
+        "project_type": project_type,
+        "graph_dir": str(graph_dir),
+        "directories_created": created["directories"],
+        "files_created": created["files"],
+        "has_claude": has_claude,
+        "plugin_installed": plugin_installed,
+        "next_steps": next_steps,
+    }

{htmlgraph-0.26.21.dist-info → htmlgraph-0.26.23.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.26.21
+Version: 0.26.23
 Summary: HTML is All You Need - Graph database on web standards
 Project-URL: Homepage, https://github.com/Shakes-tzd/htmlgraph
 Project-URL: Documentation, https://github.com/Shakes-tzd/htmlgraph#readme