htmlgraph 0.21.0__py3-none-any.whl → 0.23.0__py3-none-any.whl

htmlgraph/operations/hooks.py

@@ -0,0 +1,349 @@
+"""Git hook operations for HtmlGraph."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class HookInstallResult:
+    installed: list[str]
+    skipped: list[str]
+    warnings: list[str]
+    config_used: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class HookListResult:
+    enabled: list[str]
+    disabled: list[str]
+    missing: list[str]
+
+
+@dataclass(frozen=True)
+class HookValidationResult:
+    valid: bool
+    errors: list[str]
+    warnings: list[str]
+
+
+class HookConfigError(ValueError):
+    """Invalid hook configuration."""
+
+
+class HookInstallError(RuntimeError):
+    """Hook installation failed."""
+
+
+def _load_hook_config(project_dir: Path) -> dict[str, Any]:
+    """Load hook configuration from project."""
+    config_path = project_dir / ".htmlgraph" / "hooks-config.json"
+
+    # Default configuration
+    default_config: dict[str, Any] = {
+        "enabled_hooks": [
+            "post-commit",
+            "post-checkout",
+            "post-merge",
+            "pre-push",
+        ],
+        "use_symlinks": True,
+        "backup_existing": True,
+        "chain_existing": True,
+    }
+
+    if not config_path.exists():
+        return default_config
+
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            user_config = json.load(f)
+            # Merge with defaults
+            config = default_config.copy()
+            config.update(user_config)
+            return config
+    except Exception as e:
+        raise HookConfigError(f"Failed to load hook config: {e}") from e
+
+
+def _validate_environment(project_dir: Path) -> None:
+    """Validate that environment is ready for hook installation."""
+    git_dir = project_dir / ".git"
+    htmlgraph_dir = project_dir / ".htmlgraph"
+
+    if not git_dir.exists():
+        raise HookInstallError("Not a git repository (no .git directory found)")
+
+    if not htmlgraph_dir.exists():
+        raise HookInstallError("HtmlGraph not initialized (run 'htmlgraph init' first)")
+
+    git_hooks_dir = git_dir / "hooks"
+    if not git_hooks_dir.exists():
+        try:
+            git_hooks_dir.mkdir(parents=True)
+        except Exception as e:
+            raise HookInstallError(f"Cannot create .git/hooks directory: {e}") from e
+
+
+def _install_single_hook(
+    hook_name: str,
+    *,
+    project_dir: Path,
+    config: dict[str, Any],
+    force: bool = False,
+) -> tuple[bool, str]:
+    """Install a single git hook."""
+    from htmlgraph.hooks import HOOKS_DIR
+
+    # Check if hook is enabled
+    if hook_name not in config.get("enabled_hooks", []):
+        return False, f"Hook '{hook_name}' is disabled in configuration"
+
+    # Source hook file
+    hook_source = HOOKS_DIR / f"{hook_name}.sh"
+    if not hook_source.exists():
+        return False, f"Hook template not found: {hook_source}"
+
+    # Destination in .htmlgraph/hooks/ (versioned)
+    htmlgraph_dir = project_dir / ".htmlgraph"
+    versioned_hooks_dir = htmlgraph_dir / "hooks"
+    versioned_hooks_dir.mkdir(exist_ok=True)
+    hook_dest = versioned_hooks_dir / f"{hook_name}.sh"
+
+    # Git hooks directory
+    git_dir = project_dir / ".git"
+    git_hooks_dir = git_dir / "hooks"
+    git_hook_path = git_hooks_dir / hook_name
+
+    # Copy hook to .htmlgraph/hooks/ (versioned)
+    try:
+        shutil.copy(hook_source, hook_dest)
+        hook_dest.chmod(0o755)
+    except Exception as e:
+        raise HookInstallError(f"Failed to copy hook to {hook_dest}: {e}") from e
+
+    # Handle existing git hook
+    if git_hook_path.exists() and not force:
+        if config.get("backup_existing", True):
+            backup_path = git_hook_path.with_suffix(".backup")
+            if not backup_path.exists():
+                shutil.copy(git_hook_path, backup_path)
+
+            if config.get("chain_existing", True):
+                # Create chained hook
+                return _create_chained_hook(
+                    hook_name, hook_dest, git_hook_path, backup_path
+                )
+            else:
+                return False, (
+                    f"Hook {hook_name} already exists. "
+                    f"Backed up to {backup_path}. "
+                    f"Use force=True to overwrite."
+                )
+
+    # Install hook (symlink or copy)
+    use_symlinks = not force and config.get("use_symlinks", True)
+
+    try:
+        if use_symlinks:
+            # Remove existing symlink if present
+            if git_hook_path.is_symlink():
+                git_hook_path.unlink()
+
+            git_hook_path.symlink_to(hook_dest.resolve())
+            return True, f"Installed {hook_name} (symlink)"
+        else:
+            shutil.copy(hook_dest, git_hook_path)
+            git_hook_path.chmod(0o755)
+            return True, f"Installed {hook_name} (copy)"
+    except Exception as e:
+        raise HookInstallError(f"Failed to install {hook_name}: {e}") from e
+
+
+def _create_chained_hook(
+    hook_name: str, htmlgraph_hook: Path, git_hook: Path, backup_hook: Path
+) -> tuple[bool, str]:
+    """Create a chained hook that runs both existing and HtmlGraph hooks."""
+    chain_content = f'''#!/bin/bash
+# Chained hook - runs existing hook then HtmlGraph hook
+
+# Run existing hook
+if [ -f "{backup_hook}" ]; then
+  "{backup_hook}" || exit $?
+fi
+
+# Run HtmlGraph hook
+if [ -f "{htmlgraph_hook}" ]; then
+  "{htmlgraph_hook}" || true
+fi
+'''
+
+    try:
+        git_hook.write_text(chain_content, encoding="utf-8")
+        git_hook.chmod(0o755)
+        return True, f"Installed {hook_name} (chained)"
+    except Exception as e:
+        raise HookInstallError(f"Failed to create chained hook: {e}") from e
+
+
+def install_hooks(*, project_dir: Path, use_copy: bool = False) -> HookInstallResult:
+    """
+    Install HtmlGraph git hooks into the project.
+
+    Args:
+        project_dir: Project root directory
+        use_copy: Force copy instead of symlink
+
+    Returns:
+        HookInstallResult with installation details
+
+    Raises:
+        HookInstallError: If installation fails
+        HookConfigError: If configuration is invalid
+    """
+    project_dir = Path(project_dir).resolve()
+
+    # Validate environment
+    _validate_environment(project_dir)
+
+    # Load configuration
+    config = _load_hook_config(project_dir)
+
+    # Override use_symlinks if use_copy is requested
+    if use_copy:
+        config["use_symlinks"] = False
+
+    installed: list[str] = []
+    skipped: list[str] = []
+    warnings: list[str] = []
+
+    # Install each enabled hook
+    for hook_name in config.get("enabled_hooks", []):
+        try:
+            success, message = _install_single_hook(
+                hook_name,
+                project_dir=project_dir,
+                config=config,
+                force=False,
+            )
+
+            if success:
+                installed.append(hook_name)
+            else:
+                skipped.append(hook_name)
+                warnings.append(message)
+        except Exception as e:
+            skipped.append(hook_name)
+            warnings.append(f"{hook_name}: {e}")
+
+    return HookInstallResult(
+        installed=installed,
+        skipped=skipped,
+        warnings=warnings,
+        config_used=config,
+    )
+
+
+def list_hooks(*, project_dir: Path) -> HookListResult:
+    """
+    Return enabled/disabled/missing hooks for a project.
+
+    Args:
+        project_dir: Project root directory
+
+    Returns:
+        HookListResult with hook status
+    """
+    from htmlgraph.hooks import AVAILABLE_HOOKS
+
+    project_dir = Path(project_dir).resolve()
+    git_dir = project_dir / ".git"
+
+    # Load configuration
+    try:
+        config = _load_hook_config(project_dir)
+    except HookConfigError:
+        config = {"enabled_hooks": []}
+
+    enabled_hooks = config.get("enabled_hooks", [])
+
+    enabled: list[str] = []
+    disabled: list[str] = []
+    missing: list[str] = []
+
+    for hook_name in AVAILABLE_HOOKS:
+        git_hook_path = git_dir / "hooks" / hook_name
+        is_enabled = hook_name in enabled_hooks
+
+        if is_enabled:
+            if git_hook_path.exists():
+                enabled.append(hook_name)
+            else:
+                missing.append(hook_name)
+        else:
+            disabled.append(hook_name)
+
+    return HookListResult(
+        enabled=enabled,
+        disabled=disabled,
+        missing=missing,
+    )
+
+
+def validate_hook_config(*, project_dir: Path) -> HookValidationResult:
+    """
+    Validate hook configuration for a project.
+
+    Args:
+        project_dir: Project root directory
+
+    Returns:
+        HookValidationResult with validation status
+    """
+    from htmlgraph.hooks import AVAILABLE_HOOKS
+
+    project_dir = Path(project_dir).resolve()
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # Check git repository
+    git_dir = project_dir / ".git"
+    if not git_dir.exists():
+        errors.append("Not a git repository (no .git directory found)")
+
+    # Check HtmlGraph initialization
+    htmlgraph_dir = project_dir / ".htmlgraph"
+    if not htmlgraph_dir.exists():
+        errors.append("HtmlGraph not initialized (run 'htmlgraph init' first)")
+
+    # Load and validate configuration
+    try:
+        config = _load_hook_config(project_dir)
+
+        # Validate enabled_hooks
+        enabled_hooks = config.get("enabled_hooks", [])
+        if not isinstance(enabled_hooks, list):
+            errors.append("enabled_hooks must be a list")
+        else:
+            for hook_name in enabled_hooks:
+                if hook_name not in AVAILABLE_HOOKS:
+                    warnings.append(f"Unknown hook '{hook_name}' in configuration")
+
+        # Validate boolean options
+        for key in ["use_symlinks", "backup_existing", "chain_existing"]:
+            value = config.get(key)
+            if value is not None and not isinstance(value, bool):
+                errors.append(f"{key} must be a boolean")
+
+    except HookConfigError as e:
+        errors.append(str(e))
+
+    return HookValidationResult(
+        valid=len(errors) == 0,
+        errors=errors,
+        warnings=warnings,
+    )

htmlgraph/operations/server.py

@@ -0,0 +1,302 @@
+"""Server operations for HtmlGraph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ServerHandle:
+    url: str
+    port: int
+    host: str
+    server: Any | None = None
+
+
+@dataclass(frozen=True)
+class ServerStatus:
+    running: bool
+    url: str | None = None
+    port: int | None = None
+    host: str | None = None
+
+
+@dataclass(frozen=True)
+class ServerStartResult:
+    handle: ServerHandle
+    warnings: list[str]
+    config_used: dict[str, Any]
+
+
+class ServerStartError(RuntimeError):
+    """Server failed to start."""
+
+
+class PortInUseError(ServerStartError):
+    """Requested port is already in use."""
+
+
+def start_server(
+    *,
+    port: int,
+    graph_dir: Path,
+    static_dir: Path,
+    host: str = "localhost",
+    watch: bool = True,
+    auto_port: bool = False,
+) -> ServerStartResult:
+    """
+    Start the HtmlGraph server with validated configuration.
+
+    Args:
+        port: Port to listen on
+        graph_dir: Directory containing graph data (.htmlgraph/)
+        static_dir: Directory for static files (index.html, etc.)
+        host: Host to bind to
+        watch: Enable file watching for auto-reload
+        auto_port: Automatically find available port if specified port is in use
+
+    Returns:
+        ServerStartResult with handle, warnings, and config used
+
+    Raises:
+        PortInUseError: If port is in use and auto_port=False
+        ServerStartError: If server fails to start
+    """
+    from http.server import HTTPServer
+
+    from htmlgraph.analytics_index import AnalyticsIndex
+    from htmlgraph.event_log import JsonlEventLog
+    from htmlgraph.file_watcher import GraphWatcher
+    from htmlgraph.graph import HtmlGraph
+    from htmlgraph.server import HtmlGraphAPIHandler, sync_dashboard_files
+
+    warnings: list[str] = []
+    original_port = port
+
+    # Handle auto-port selection
+    if auto_port and _check_port_in_use(port, host):
+        port = _find_available_port(port + 1)
+        warnings.append(f"Port {original_port} is in use, using {port} instead")
+
+    # Check if port is still in use (and we're not in auto-port mode)
+    if not auto_port and _check_port_in_use(port, host):
+        raise PortInUseError(
+            f"Port {port} is already in use. Use auto_port=True or choose a different port."
+        )
+
+    # Auto-sync dashboard files
+    try:
+        if sync_dashboard_files(static_dir):
+            warnings.append(
+                "Dashboard files out of sync, synced dashboard.html → index.html"
+            )
+    except PermissionError as e:
+        warnings.append(f"Unable to sync dashboard files: {e}")
+    except Exception as e:
+        warnings.append(f"Error during dashboard sync: {e}")
+
+    # Create graph directories
+    graph_dir.mkdir(parents=True, exist_ok=True)
+    for collection in HtmlGraphAPIHandler.COLLECTIONS:
+        (graph_dir / collection).mkdir(exist_ok=True)
+
+    # Copy default stylesheet
+    styles_dest = graph_dir / "styles.css"
+    if not styles_dest.exists():
+        styles_src = Path(__file__).parent.parent / "styles.css"
+        if styles_src.exists():
+            styles_dest.write_text(styles_src.read_text())
+
+    # Build analytics index if needed
+    events_dir = graph_dir / "events"
+    db_path = graph_dir / "index.sqlite"
+    index_needs_build = (
+        not db_path.exists() and events_dir.exists() and any(events_dir.glob("*.jsonl"))
+    )
+
+    if index_needs_build:
+        try:
+            log = JsonlEventLog(events_dir)
+            index = AnalyticsIndex(db_path)
+            events = (event for _, event in log.iter_events())
+            index.rebuild_from_events(events)
+        except Exception as e:
+            warnings.append(f"Failed to build analytics index: {e}")
+
+    # Configure handler
+    HtmlGraphAPIHandler.graph_dir = graph_dir
+    HtmlGraphAPIHandler.static_dir = static_dir
+    HtmlGraphAPIHandler.graphs = {}
+    HtmlGraphAPIHandler.analytics_db = None
+
+    # Start HTTP server
+    try:
+        server = HTTPServer((host, port), HtmlGraphAPIHandler)
+    except OSError as e:
+        if e.errno == 48 or "Address already in use" in str(e):
+            raise PortInUseError(f"Port {port} is already in use") from e
+        raise ServerStartError(f"Failed to start server: {e}") from e
+
+    # Start file watcher if enabled
+    watcher = None
+    if watch:
+
+        def get_graph(collection: str) -> HtmlGraph:
+            """Callback to get graph instance for a collection."""
+            handler = HtmlGraphAPIHandler
+            if collection not in handler.graphs:
+                collection_dir = handler.graph_dir / collection
+                handler.graphs[collection] = HtmlGraph(
+                    collection_dir, stylesheet_path="../styles.css", auto_load=True
+                )
+            return handler.graphs[collection]
+
+        watcher = GraphWatcher(
+            graph_dir=graph_dir,
+            collections=HtmlGraphAPIHandler.COLLECTIONS,
+            get_graph_callback=get_graph,
+        )
+        watcher.start()
+
+    # Create handle
+    handle = ServerHandle(
+        url=f"http://{host}:{port}",
+        port=port,
+        host=host,
+        server={"httpserver": server, "watcher": watcher},
+    )
+
+    # Configuration used
+    config_used = {
+        "port": port,
+        "original_port": original_port,
+        "host": host,
+        "graph_dir": str(graph_dir),
+        "static_dir": str(static_dir),
+        "watch": watch,
+        "auto_port": auto_port,
+    }
+
+    return ServerStartResult(
+        handle=handle,
+        warnings=warnings,
+        config_used=config_used,
+    )
+
+
+def stop_server(handle: ServerHandle) -> None:
+    """
+    Stop a running HtmlGraph server.
+
+    Args:
+        handle: ServerHandle returned from start_server()
+
+    Raises:
+        ServerStartError: If shutdown fails
+    """
+    if handle.server is None:
+        return
+
+    try:
+        # Extract server components
+        if isinstance(handle.server, dict):
+            httpserver = handle.server.get("httpserver")
+            watcher = handle.server.get("watcher")
+
+            # Stop file watcher first
+            if watcher is not None:
+                try:
+                    watcher.stop()
+                except Exception:
+                    pass  # Best effort
+
+            # Shutdown HTTP server
+            if httpserver is not None:
+                httpserver.shutdown()
+        else:
+            # Assume it's the HTTPServer directly
+            handle.server.shutdown()
+    except Exception as e:
+        raise ServerStartError(f"Failed to stop server: {e}") from e
+
+
+def get_server_status(handle: ServerHandle | None = None) -> ServerStatus:
+    """
+    Return server status for a handle or best-effort local check.
+
+    Args:
+        handle: Optional ServerHandle to check
+
+    Returns:
+        ServerStatus indicating whether server is running
+    """
+    if handle is None:
+        # No handle provided - cannot determine status
+        return ServerStatus(running=False)
+
+    # Check if server is running by testing the port
+    try:
+        is_running = not _check_port_in_use(handle.port, handle.host)
+        return ServerStatus(
+            running=is_running,
+            url=handle.url if is_running else None,
+            port=handle.port if is_running else None,
+            host=handle.host if is_running else None,
+        )
+    except Exception:
+        return ServerStatus(running=False)
+
+
+# Helper functions (private)
+
+
+def _check_port_in_use(port: int, host: str = "localhost") -> bool:
+    """
+    Check if a port is already in use.
+
+    Args:
+        port: Port number to check
+        host: Host to check on
+
+    Returns:
+        True if port is in use, False otherwise
+    """
+    import socket
+
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind((host, port))
+            return False
+    except OSError:
+        return True
+
+
+def _find_available_port(start_port: int = 8080, max_attempts: int = 10) -> int:
+    """
+    Find an available port starting from start_port.
+
+    Args:
+        start_port: Port to start searching from
+        max_attempts: Maximum number of ports to try
+
+    Returns:
+        Available port number
+
+    Raises:
+        ServerStartError: If no available port found in range
+    """
+    import socket
+
+    for port in range(start_port, start_port + max_attempts):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("", port))
+                return port
+        except OSError:
+            continue
+    raise ServerStartError(
+        f"No available ports found in range {start_port}-{start_port + max_attempts}"
+    )

htmlgraph/orchestration/__init__.py

@@ -0,0 +1,39 @@
+"""Orchestration utilities for multi-agent coordination."""
+
+from .headless_spawner import AIResult, HeadlessSpawner
+from .model_selection import (
+    BudgetMode,
+    ComplexityLevel,
+    ModelSelection,
+    TaskType,
+    get_fallback_chain,
+    select_model,
+)
+from .task_coordination import (
+    delegate_with_id,
+    generate_task_id,
+    get_results_by_task_id,
+    parallel_delegate,
+    save_task_results,
+    validate_and_save,
+)
+
+__all__ = [
+    # Headless AI spawning
+    "HeadlessSpawner",
+    "AIResult",
+    # Model selection
+    "ModelSelection",
+    "TaskType",
+    "ComplexityLevel",
+    "BudgetMode",
+    "select_model",
+    "get_fallback_chain",
+    # Task coordination
+    "delegate_with_id",
+    "generate_task_id",
+    "get_results_by_task_id",
+    "parallel_delegate",
+    "save_task_results",
+    "validate_and_save",
+]