htmlgraph 0.22.0__py3-none-any.whl → 0.23.1__py3-none-any.whl

htmlgraph/operations/README.md

@@ -0,0 +1,62 @@
+# HtmlGraph Operations Layer
+
+This module defines a shared, backend operations layer for HtmlGraph. The CLI and SDK
+should call these operations rather than duplicating logic. The operations layer is
+pure Python, stateless, and returns structured data instead of printing.
+
+## Design Principles
+
+- Stateless: all inputs passed explicitly; no global CLI state.
+- Typed: full type hints, dataclasses for results.
+- Structured results: return data, warnings, and metadata; no printing.
+- Exceptions for errors: no sys.exit.
+- Path-first: accept Path objects for filesystem inputs.
+- Reusable: callable from CLI, SDK, and tests.
+
+## Module Structure
+
+- `operations/server.py`   Server startup and lifecycle helpers
+- `operations/hooks.py`    Git hook installation and configuration
+- `operations/events.py`   Event export, index rebuild, event queries
+- `operations/analytics.py` Analytics summaries and report generation
+
+## Example Signature
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+@dataclass
+class ServerHandle:
+    url: str
+    port: int
+    host: str
+
+@dataclass
+class ServerStartResult:
+    handle: ServerHandle
+    warnings: list[str]
+    config_used: dict[str, Any]
+
+class ServerStartError(RuntimeError):
+    pass
+
+
+def start_server(
+    *,
+    port: int,
+    graph_dir: Path,
+    host: str = "localhost",
+    watch: bool = True,
+    auto_port: bool = False,
+) -> ServerStartResult:
+    """Start HtmlGraph server with validated config."""
+    raise NotImplementedError
+```
+
+## Conventions
+
+- Functions should avoid any CLI-specific formatting.
+- Results should be serializable for JSON output.
+- Keep modules focused on a single domain (server, hooks, events, analytics).

htmlgraph/operations/__init__.py

@@ -0,0 +1,61 @@
+"""Shared operations layer for HtmlGraph CLI and SDK."""
+
+from .analytics import (
+    AnalyticsProjectResult,
+    AnalyticsSessionResult,
+    analyze_project,
+    analyze_session,
+)
+from .events import (
+    EventExportResult,
+    EventQueryResult,
+    EventRebuildResult,
+    EventStats,
+    export_sessions,
+    get_event_stats,
+    query_events,
+    rebuild_index,
+)
+from .hooks import (
+    HookInstallResult,
+    HookListResult,
+    HookValidationResult,
+    install_hooks,
+    list_hooks,
+    validate_hook_config,
+)
+from .server import (
+    ServerHandle,
+    ServerStartResult,
+    ServerStatus,
+    get_server_status,
+    start_server,
+    stop_server,
+)
+
+__all__ = [
+    "AnalyticsProjectResult",
+    "AnalyticsSessionResult",
+    "analyze_project",
+    "analyze_session",
+    "EventExportResult",
+    "EventQueryResult",
+    "EventRebuildResult",
+    "EventStats",
+    "export_sessions",
+    "get_event_stats",
+    "query_events",
+    "rebuild_index",
+    "HookInstallResult",
+    "HookListResult",
+    "HookValidationResult",
+    "install_hooks",
+    "list_hooks",
+    "validate_hook_config",
+    "ServerHandle",
+    "ServerStartResult",
+    "ServerStatus",
+    "start_server",
+    "stop_server",
+    "get_server_status",
+]

htmlgraph/operations/analytics.py

@@ -0,0 +1,338 @@
+"""Analytics operations for HtmlGraph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from htmlgraph import SDK
+from htmlgraph.converter import html_to_session
+
+
+@dataclass(frozen=True)
+class AnalyticsSessionResult:
+    """Result of analyzing a single session."""
+
+    session_id: str
+    metrics: dict[str, Any]
+    warnings: list[str]
+
+
+@dataclass(frozen=True)
+class AnalyticsProjectResult:
+    """Result of analyzing project-wide analytics."""
+
+    metrics: dict[str, Any]
+    warnings: list[str]
+
+
+@dataclass(frozen=True)
+class RecommendationsResult:
+    """Result of getting work recommendations."""
+
+    recommendations: list[dict[str, Any]]
+    reasoning: dict[str, Any]
+    warnings: list[str]
+
+
+class AnalyticsOperationError(RuntimeError):
+    """Base error for analytics operations."""
+
+
+def analyze_session(*, graph_dir: Path, session_id: str) -> AnalyticsSessionResult:
+    """
+    Compute analytics for a single session.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+        session_id: ID of the session to analyze
+
+    Returns:
+        AnalyticsSessionResult with session metrics and warnings
+
+    Raises:
+        AnalyticsOperationError: If session cannot be analyzed
+    """
+    warnings: list[str] = []
+
+    # Validate inputs
+    if not graph_dir.exists():
+        raise AnalyticsOperationError(f"Graph directory does not exist: {graph_dir}")
+
+    session_path = graph_dir / "sessions" / f"{session_id}.html"
+    if not session_path.exists():
+        raise AnalyticsOperationError(f"Session not found: {session_id}")
+
+    try:
+        # Load session
+        session = html_to_session(session_path)
+    except Exception as e:
+        raise AnalyticsOperationError(f"Failed to load session {session_id}: {e}")
+
+    try:
+        # Initialize SDK with minimal agent
+        sdk = SDK(directory=str(graph_dir), agent="analytics-ops")
+
+        # Compute metrics
+        metrics: dict[str, Any] = {}
+
+        # Work distribution
+        try:
+            work_dist = sdk.analytics.work_type_distribution(session_id=session_id)
+            metrics["work_distribution"] = work_dist
+        except Exception as e:
+            warnings.append(f"Failed to compute work distribution: {e}")
+            metrics["work_distribution"] = {}
+
+        # Spike-to-feature ratio
+        try:
+            spike_ratio = sdk.analytics.spike_to_feature_ratio(session_id=session_id)
+            metrics["spike_to_feature_ratio"] = spike_ratio
+        except Exception as e:
+            warnings.append(f"Failed to compute spike ratio: {e}")
+            metrics["spike_to_feature_ratio"] = 0.0
+
+        # Maintenance burden
+        try:
+            maintenance = sdk.analytics.maintenance_burden(session_id=session_id)
+            metrics["maintenance_burden"] = maintenance
+        except Exception as e:
+            warnings.append(f"Failed to compute maintenance burden: {e}")
+            metrics["maintenance_burden"] = 0.0
+
+        # Primary work type
+        try:
+            primary = sdk.analytics.calculate_session_primary_work_type(session_id)
+            metrics["primary_work_type"] = primary
+        except Exception as e:
+            warnings.append(f"Failed to compute primary work type: {e}")
+            metrics["primary_work_type"] = None
+
+        # Work breakdown (event counts)
+        try:
+            breakdown = sdk.analytics.calculate_session_work_breakdown(session_id)
+            metrics["work_breakdown"] = breakdown
+            metrics["total_events"] = sum(breakdown.values()) if breakdown else 0
+        except Exception as e:
+            warnings.append(f"Failed to compute work breakdown: {e}")
+            metrics["work_breakdown"] = {}
+            metrics["total_events"] = session.event_count
+
+        # Transition time metrics
+        try:
+            transition = sdk.analytics.transition_time_metrics(session_id=session_id)
+            metrics["transition_metrics"] = transition
+        except Exception as e:
+            warnings.append(f"Failed to compute transition metrics: {e}")
+            metrics["transition_metrics"] = {}
+
+        # Session metadata
+        metrics["session_id"] = session.id
+        metrics["agent"] = session.agent
+        metrics["status"] = session.status
+        metrics["started_at"] = session.started_at.isoformat()
+        if session.ended_at:
+            metrics["ended_at"] = session.ended_at.isoformat()
+
+        return AnalyticsSessionResult(
+            session_id=session_id, metrics=metrics, warnings=warnings
+        )
+
+    except AnalyticsOperationError:
+        raise
+    except Exception as e:
+        raise AnalyticsOperationError(f"Failed to analyze session {session_id}: {e}")
+
+
+def analyze_project(*, graph_dir: Path) -> AnalyticsProjectResult:
+    """
+    Compute analytics for the project.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+
+    Returns:
+        AnalyticsProjectResult with project metrics and warnings
+
+    Raises:
+        AnalyticsOperationError: If project cannot be analyzed
+    """
+    warnings: list[str] = []
+
+    # Validate inputs
+    if not graph_dir.exists():
+        raise AnalyticsOperationError(f"Graph directory does not exist: {graph_dir}")
+
+    sessions_dir = graph_dir / "sessions"
+    if not sessions_dir.exists():
+        warnings.append("No sessions directory found")
+        return AnalyticsProjectResult(metrics={"total_sessions": 0}, warnings=warnings)
+
+    try:
+        # Initialize SDK
+        sdk = SDK(directory=str(graph_dir), agent="analytics-ops")
+
+        # Get session count
+        session_files = sorted(
+            sessions_dir.glob("*.html"), key=lambda p: p.stat().st_mtime, reverse=True
+        )
+        total_sessions = len(session_files)
+
+        # Compute metrics
+        metrics: dict[str, Any] = {
+            "total_sessions": total_sessions,
+        }
+
+        if total_sessions == 0:
+            warnings.append("No sessions found in project")
+            return AnalyticsProjectResult(metrics=metrics, warnings=warnings)
+
+        # Project-wide work distribution
+        try:
+            work_dist = sdk.analytics.work_type_distribution()
+            metrics["work_distribution"] = work_dist
+        except Exception as e:
+            warnings.append(f"Failed to compute work distribution: {e}")
+            metrics["work_distribution"] = {}
+
+        # Project-wide spike-to-feature ratio
+        try:
+            spike_ratio = sdk.analytics.spike_to_feature_ratio()
+            metrics["spike_to_feature_ratio"] = spike_ratio
+        except Exception as e:
+            warnings.append(f"Failed to compute spike ratio: {e}")
+            metrics["spike_to_feature_ratio"] = 0.0
+
+        # Project-wide maintenance burden
+        try:
+            maintenance = sdk.analytics.maintenance_burden()
+            metrics["maintenance_burden"] = maintenance
+        except Exception as e:
+            warnings.append(f"Failed to compute maintenance burden: {e}")
+            metrics["maintenance_burden"] = 0.0
+
+        # Project-wide transition metrics
+        try:
+            transition = sdk.analytics.transition_time_metrics()
+            metrics["transition_metrics"] = transition
+        except Exception as e:
+            warnings.append(f"Failed to compute transition metrics: {e}")
+            metrics["transition_metrics"] = {}
+
+        # Session type breakdown
+        try:
+            from htmlgraph import WorkType
+
+            spike_sessions = sdk.analytics.get_sessions_by_work_type(
+                WorkType.SPIKE.value
+            )
+            feature_sessions = sdk.analytics.get_sessions_by_work_type(
+                WorkType.FEATURE.value
+            )
+            maintenance_sessions = sdk.analytics.get_sessions_by_work_type(
+                WorkType.MAINTENANCE.value
+            )
+
+            metrics["session_types"] = {
+                "spike": len(spike_sessions),
+                "feature": len(feature_sessions),
+                "maintenance": len(maintenance_sessions),
+            }
+        except Exception as e:
+            warnings.append(f"Failed to compute session types: {e}")
+            metrics["session_types"] = {}
+
+        # Recent sessions (metadata only)
+        try:
+            recent_sessions = []
+            for session_path in session_files[:5]:  # Top 5 most recent
+                try:
+                    session = html_to_session(session_path)
+                    primary = (
+                        sdk.analytics.calculate_session_primary_work_type(session.id)
+                        or "unknown"
+                    )
+                    recent_sessions.append(
+                        {
+                            "session_id": session.id,
+                            "agent": session.agent,
+                            "started_at": session.started_at.isoformat(),
+                            "status": session.status,
+                            "primary_work_type": primary,
+                        }
+                    )
+                except Exception as e:
+                    warnings.append(f"Failed to load session {session_path.name}: {e}")
+                    continue
+
+            metrics["recent_sessions"] = recent_sessions
+        except Exception as e:
+            warnings.append(f"Failed to load recent sessions: {e}")
+            metrics["recent_sessions"] = []
+
+        return AnalyticsProjectResult(metrics=metrics, warnings=warnings)
+
+    except AnalyticsOperationError:
+        raise
+    except Exception as e:
+        raise AnalyticsOperationError(f"Failed to analyze project: {e}")
+
+
+def get_recommendations(*, graph_dir: Path) -> RecommendationsResult:
+    """
+    Get work recommendations based on project state.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+
+    Returns:
+        RecommendationsResult with recommendations, reasoning, and warnings
+
+    Raises:
+        AnalyticsOperationError: If recommendations cannot be generated
+    """
+    warnings: list[str] = []
+
+    # Validate inputs
+    if not graph_dir.exists():
+        raise AnalyticsOperationError(f"Graph directory does not exist: {graph_dir}")
+
+    try:
+        # Initialize SDK
+        sdk = SDK(directory=str(graph_dir), agent="analytics-ops")
+
+        # Get recommendations
+        try:
+            task_recs = sdk.dep_analytics.recommend_next_tasks(agent_count=5)
+            recommendations = [
+                {
+                    "id": rec.id,
+                    "title": rec.title,
+                    "priority": rec.priority,
+                    "score": rec.score,
+                    "reasons": rec.reasons,
+                    "unlocks": rec.unlocks,
+                    "estimated_effort": rec.estimated_effort,
+                }
+                for rec in task_recs.recommendations
+            ]
+            reasoning = {
+                "recommendation_count": len(task_recs.recommendations),
+                "parallel_suggestions": task_recs.parallel_suggestions,
+            }
+        except Exception as e:
+            raise AnalyticsOperationError(f"Failed to generate recommendations: {e}")
+
+        # Add contextual warnings based on recommendations
+        if not recommendations:
+            warnings.append("No recommendations available - project may be empty")
+
+        return RecommendationsResult(
+            recommendations=recommendations, reasoning=reasoning, warnings=warnings
+        )
+
+    except AnalyticsOperationError:
+        raise
+    except Exception as e:
+        raise AnalyticsOperationError(f"Failed to get recommendations: {e}")

htmlgraph/operations/events.py

@@ -0,0 +1,243 @@
+"""Event and analytics index operations for HtmlGraph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EventRebuildResult:
+    """Result of rebuilding the event index."""
+
+    db_path: Path
+    inserted: int
+    skipped: int
+
+
+@dataclass(frozen=True)
+class EventStats:
+    """Statistics about events in the system."""
+
+    total_events: int
+    session_count: int
+    file_count: int
+
+
+@dataclass(frozen=True)
+class EventQueryResult:
+    """Result of querying events."""
+
+    events: list[dict[str, Any]]
+    total: int
+
+
+@dataclass(frozen=True)
+class EventExportResult:
+    """Result of exporting sessions to JSONL."""
+
+    written: int
+    skipped: int
+    failed: int
+
+
+class EventOperationError(RuntimeError):
+    """Base error for event operations."""
+
+
+def export_sessions(*, graph_dir: Path, overwrite: bool = False) -> EventExportResult:
+    """
+    Export legacy session HTML logs to JSONL events.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+        overwrite: Whether to overwrite existing JSONL files
+
+    Returns:
+        EventExportResult with counts of written, skipped, failed files
+
+    Raises:
+        EventOperationError: If graph_dir doesn't exist or isn't a directory
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.event_migration import export_sessions_to_jsonl
+
+    sessions_dir = graph_dir / "sessions"
+    events_dir = graph_dir / "events"
+
+    if not sessions_dir.exists():
+        raise EventOperationError(f"Sessions directory not found: {sessions_dir}")
+
+    try:
+        result = export_sessions_to_jsonl(
+            sessions_dir=sessions_dir,
+            events_dir=events_dir,
+            overwrite=overwrite,
+            include_subdirs=False,
+        )
+        return EventExportResult(
+            written=result["written"],
+            skipped=result["skipped"],
+            failed=result["failed"],
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to export sessions: {e}") from e
+
+
+def rebuild_index(*, graph_dir: Path) -> EventRebuildResult:
+    """
+    Rebuild the SQLite analytics index from JSONL events.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+
+    Returns:
+        EventRebuildResult with db_path and counts of inserted/skipped events
+
+    Raises:
+        EventOperationError: If events directory doesn't exist or rebuild fails
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.analytics_index import AnalyticsIndex
+    from htmlgraph.event_log import JsonlEventLog
+
+    events_dir = graph_dir / "events"
+    db_path = graph_dir / "index.sqlite"
+
+    if not events_dir.exists():
+        raise EventOperationError(f"Events directory not found: {events_dir}")
+
+    try:
+        log = JsonlEventLog(events_dir)
+        index = AnalyticsIndex(db_path)
+
+        # Stream events from all JSONL files
+        events = (event for _, event in log.iter_events())
+        result = index.rebuild_from_events(events)
+
+        return EventRebuildResult(
+            db_path=db_path,
+            inserted=result["inserted"],
+            skipped=result["skipped"],
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to rebuild index: {e}") from e
+
+
+def query_events(
+    *,
+    graph_dir: Path,
+    session_id: str | None = None,
+    tool: str | None = None,
+    feature_id: str | None = None,
+    since: str | None = None,
+    limit: int | None = None,
+) -> EventQueryResult:
+    """
+    Query events from JSONL logs with optional filters.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+        session_id: Filter by session ID (None = all sessions)
+        tool: Filter by tool name (e.g., 'Bash', 'Edit')
+        feature_id: Filter by attributed feature ID
+        since: Only events after this timestamp (ISO string)
+        limit: Maximum number of events to return
+
+    Returns:
+        EventQueryResult with matching events and total count
+
+    Raises:
+        EventOperationError: If events directory doesn't exist or query fails
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.event_log import JsonlEventLog
+
+    events_dir = graph_dir / "events"
+
+    if not events_dir.exists():
+        raise EventOperationError(f"Events directory not found: {events_dir}")
+
+    try:
+        log = JsonlEventLog(events_dir)
+        events = log.query_events(
+            session_id=session_id,
+            tool=tool,
+            feature_id=feature_id,
+            since=since,
+            limit=limit,
+        )
+
+        return EventQueryResult(
+            events=events,
+            total=len(events),
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to query events: {e}") from e
+
+
+def get_event_stats(*, graph_dir: Path) -> EventStats:
+    """
+    Get statistics about events in the system.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+
+    Returns:
+        EventStats with counts of total events, sessions, and files
+
+    Raises:
+        EventOperationError: If events directory doesn't exist or stats collection fails
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.event_log import JsonlEventLog
+
+    events_dir = graph_dir / "events"
+
+    if not events_dir.exists():
+        # No events directory means no events
+        return EventStats(
+            total_events=0,
+            session_count=0,
+            file_count=0,
+        )
+
+    try:
+        log = JsonlEventLog(events_dir)
+
+        # Count total events and track unique sessions
+        total_events = 0
+        sessions: set[str] = set()
+
+        for _, event in log.iter_events():
+            total_events += 1
+            if session_id := event.get("session_id"):
+                sessions.add(session_id)
+
+        # Count JSONL files
+        file_count = len(list(events_dir.glob("*.jsonl")))
+
+        return EventStats(
+            total_events=total_events,
+            session_count=len(sessions),
+            file_count=file_count,
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to get event stats: {e}") from e