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

htmlgraph/operations/initialization.py.backup

@@ -0,0 +1,228 @@
+"""HtmlGraph initialization operations.
+
+This module provides functions for initializing the .htmlgraph directory structure,
+creating necessary files, and optionally installing Git hooks.
+
+The initialization process includes:
+1. Directory structure creation (.htmlgraph with subdirectories)
+2. Database initialization (htmlgraph.db)
+3. Index creation (index.sqlite)
+4. Configuration files
+5. Optional Git hooks installation
+
+Extracted from monolithic cmd_init() implementation for better maintainability.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.cli.models import InitConfig, InitResult, ValidationResult
+
+
+# Default collections to create
+DEFAULT_COLLECTIONS = [
+    "features",
+    "bugs",
+    "chores",
+    "spikes",
+    "epics",
+    "phases",
+    "tracks",
+    "sessions",
+    "insights",
+    "metrics",
+    "agents",
+    "cigs",
+]
+
+# Additional directories
+ADDITIONAL_DIRECTORIES = [
+    "events",
+    "logs",
+    "archive-index",
+    "archives",
+]
+
+
+def initialize_htmlgraph(config: InitConfig) -> InitResult:
+    """Initialize .htmlgraph directory structure.
+
+    Creates the standard HtmlGraph directory structure:
+    - .htmlgraph/
+      - features/
+      - sessions/
+      - spikes/
+      - bugs/
+      - tracks/
+      - events/
+      - logs/
+
+    Args:
+        config: Initialization configuration
+
+    Returns:
+        InitResult with success status and details
+    """
+    try:
+        # Resolve directory path
+        base_dir = Path(config.dir).resolve()
+        htmlgraph_dir = base_dir / ".htmlgraph"
+
+        created_dirs: list[str] = []
+        updated_files: list[str] = []
+
+        # Create main directory
+        if not htmlgraph_dir.exists():
+            htmlgraph_dir.mkdir(parents=True, exist_ok=True)
+            created_dirs.append(str(htmlgraph_dir))
+
+        # Create standard subdirectories
+        subdirs = [
+            "features",
+            "sessions",
+            "spikes",
+            "bugs",
+            "tracks",
+            "events",
+            "logs",
+            "logs/errors",
+        ]
+
+        for subdir in subdirs:
+            subdir_path = htmlgraph_dir / subdir
+            if not subdir_path.exists():
+                subdir_path.mkdir(parents=True, exist_ok=True)
+                created_dirs.append(str(subdir_path))
+
+        # Create .gitkeep in events directory (unless disabled)
+        if not config.no_events_keep:
+            events_dir = htmlgraph_dir / "events"
+            gitkeep_file = events_dir / ".gitkeep"
+            if not gitkeep_file.exists():
+                gitkeep_file.touch()
+                updated_files.append(str(gitkeep_file))
+
+        # Update .gitignore (unless disabled)
+        if not config.no_update_gitignore:
+            gitignore_path = base_dir / ".gitignore"
+            gitignore_entries = [
+                "# HtmlGraph cache files",
+                ".htmlgraph/index.sqlite",
+                ".htmlgraph/htmlgraph.db",
+                ".htmlgraph/sessions/*.jsonl",
+                ".htmlgraph/events/*.jsonl",
+                ".htmlgraph/parent-activity.json",
+            ]
+
+            # Read existing .gitignore
+            existing_entries: set[str] = set()
+            if gitignore_path.exists():
+                existing_entries = set(
+                    line.strip() for line in gitignore_path.read_text().splitlines()
+                )
+
+            # Add missing entries
+            new_entries = [
+                entry for entry in gitignore_entries if entry not in existing_entries
+            ]
+
+            if new_entries:
+                mode = "a" if gitignore_path.exists() else "w"
+                with gitignore_path.open(mode) as f:
+                    if mode == "a":
+                        f.write("\n")  # Add newline before appending
+                    f.write("\n".join(new_entries) + "\n")
+                updated_files.append(str(gitignore_path))
+
+        # Initialize analytics index (unless disabled)
+        if not config.no_index:
+            from htmlgraph.analytics_index import AnalyticsIndex
+
+            index_path = htmlgraph_dir / "index.sqlite"
+            if not index_path.exists():
+                # Create empty index (will be populated on first use)
+                index = AnalyticsIndex(str(index_path))
+                index.ensure_schema()
+                created_dirs.append(str(index_path))
+
+        # Install Git hooks (if requested)
+        if config.install_hooks:
+            from htmlgraph.operations.hooks import install_hooks
+
+            try:
+                hooks_result = install_hooks(project_dir=base_dir, use_copy=False)
+                if hooks_result.installed:
+                    updated_files.extend(hooks_result.installed)
+                if hooks_result.warnings:
+                    for warning in hooks_result.warnings:
+                        print(f"Warning: {warning}", file=sys.stderr)
+            except Exception as e:
+                # Non-fatal: hooks installation failed but init succeeded
+                print(f"Warning: Failed to install hooks: {e}", file=sys.stderr)
+
+        # Interactive setup wizard (if requested)
+        if config.interactive:
+            _run_interactive_setup(htmlgraph_dir)
+
+        # Build success message
+        message_parts = []
+        if created_dirs:
+            message_parts.append(f"Created {len(created_dirs)} directories")
+        if updated_files:
+            message_parts.append(f"Updated {len(updated_files)} files")
+
+        message = ", ".join(message_parts) if message_parts else "Already initialized"
+
+        return InitResult(
+            success=True,
+            directory=htmlgraph_dir,
+            message=message,
+            created_dirs=created_dirs,
+            updated_files=updated_files,
+        )
+
+    except Exception as e:
+        return InitResult(
+            success=False,
+            directory=Path(config.dir).resolve() / ".htmlgraph",
+            error=f"Initialization failed: {e}",
+        )
+
+
+def _run_interactive_setup(htmlgraph_dir: Path) -> None:
+    """Run interactive setup wizard.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+    """
+    print("\n=== HtmlGraph Interactive Setup ===\n")
+
+    # Ask about project name
+    project_name = input("Project name (optional, press Enter to skip): ").strip()
+
+    # Ask about default agent
+    default_agent = input("Default agent name (default: claude): ").strip()
+    if not default_agent:
+        default_agent = "claude"
+
+    # Create config file
+    config_file = htmlgraph_dir / "config.json"
+    if not config_file.exists():
+        import json
+
+        config_data = {}
+        if project_name:
+            config_data["project_name"] = project_name
+        config_data["default_agent"] = default_agent
+
+        config_file.write_text(json.dumps(config_data, indent=2) + "\n")
+        print(f"\n✓ Created config file: {config_file}")
+
+    print("\n✓ Interactive setup complete!\n")

htmlgraph/operations/server.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+"""Server operations for HtmlGraph."""
+
+
+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,58 @@
+"""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 .spawner_event_tracker import SpawnerEventTracker, create_tracker_from_env
+
+# Export modular spawners for advanced usage
+from .spawners import (
+    BaseSpawner,
+    ClaudeSpawner,
+    CodexSpawner,
+    CopilotSpawner,
+    GeminiSpawner,
+)
+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 (unified interface)
+    "HeadlessSpawner",
+    "AIResult",
+    # Modular spawner implementations
+    "BaseSpawner",
+    "GeminiSpawner",
+    "CodexSpawner",
+    "CopilotSpawner",
+    "ClaudeSpawner",
+    # Spawner event tracking
+    "SpawnerEventTracker",
+    "create_tracker_from_env",
+    # 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",
+]