htmlgraph 0.27.7__py3-none-any.whl → 0.28.1__py3-none-any.whl

htmlgraph/__init__.py

@@ -123,7 +123,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.27.7"
+__version__ = "0.28.1"
 __all__ = [
     # Exceptions
     "HtmlGraphError",

htmlgraph/api/broadcast.py

@@ -0,0 +1,316 @@
+"""
+Cross-Session Broadcast Sync - Phase 2
+
+Enables real-time feature updates across multiple Claude Code sessions.
+Session A updates a feature → immediately visible in Session B without manual git pull.
+
+Features:
+- Real-time feature/track/spike updates (<100ms latency)
+- Cross-session coordination
+- Automatic synchronization
+- Audit trail for all changes
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class BroadcastEventType(str, Enum):
+    """Types of broadcast events for cross-session sync."""
+
+    FEATURE_UPDATED = "feature_updated"
+    FEATURE_CREATED = "feature_created"
+    FEATURE_DELETED = "feature_deleted"
+    TRACK_UPDATED = "track_updated"
+    SPIKE_UPDATED = "spike_updated"
+    STATUS_CHANGED = "status_changed"
+    LINK_ADDED = "link_added"
+    COMMENT_ADDED = "comment_added"
+
+
+@dataclass
+class BroadcastEvent:
+    """
+    Event for cross-session broadcasting.
+
+    Contains all information needed to synchronize changes across
+    multiple active sessions.
+    """
+
+    event_type: BroadcastEventType
+    resource_id: str  # feature_id, track_id, etc.
+    resource_type: str  # "feature", "track", "spike"
+    agent_id: str
+    session_id: str
+    payload: dict[str, Any]
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "type": "broadcast_event",
+            "event_type": self.event_type.value,
+            "resource_id": self.resource_id,
+            "resource_type": self.resource_type,
+            "agent_id": self.agent_id,
+            "session_id": self.session_id,
+            "payload": self.payload,
+            "timestamp": self.timestamp.isoformat(),
+        }
+
+
+class CrossSessionBroadcaster:
+    """
+    Broadcasts feature/track/spike updates across all active sessions.
+
+    Enables real-time coordination between multiple agents working
+    on the same project simultaneously.
+
+    Example:
+        >>> broadcaster = CrossSessionBroadcaster(websocket_manager, db_path)
+        >>> await broadcaster.broadcast_feature_update(
+        ...     feature_id="feat-123",
+        ...     agent_id="claude-1",
+        ...     session_id="sess-1",
+        ...     payload={"status": "in_progress"}
+        ... )
+        >>> # All other sessions immediately see the update
+    """
+
+    def __init__(self, websocket_manager: Any, db_path: str):
+        """
+        Initialize broadcaster.
+
+        Args:
+            websocket_manager: WebSocketManager instance for distribution
+            db_path: Path to SQLite database for audit trail
+        """
+        self.websocket_manager = websocket_manager
+        self.db_path = db_path
+        self.event_cache: dict[str, float] = {}  # Simple deduplication cache
+
+    async def broadcast_feature_update(
+        self,
+        feature_id: str,
+        agent_id: str,
+        session_id: str,
+        payload: dict[str, Any],
+    ) -> int:
+        """
+        Broadcast feature update to all sessions.
+
+        Args:
+            feature_id: Feature being updated
+            agent_id: Agent making the change
+            session_id: Source session
+            payload: Update details (title, status, description, etc.)
+
+        Returns:
+            Number of clients that received the broadcast
+        """
+        event = BroadcastEvent(
+            event_type=BroadcastEventType.FEATURE_UPDATED,
+            resource_id=feature_id,
+            resource_type="feature",
+            agent_id=agent_id,
+            session_id=session_id,
+            payload=payload,
+        )
+
+        # Broadcast to all sessions
+        clients_notified = await self.websocket_manager.broadcast_to_all_sessions(
+            event.to_dict()
+        )
+
+        logger.info(
+            f"Broadcast feature {feature_id} update to {clients_notified} clients "
+            f"(agent={agent_id}, session={session_id})"
+        )
+
+        return int(clients_notified)
+
+    async def broadcast_feature_created(
+        self,
+        feature_id: str,
+        agent_id: str,
+        session_id: str,
+        payload: dict[str, Any],
+    ) -> int:
+        """
+        Broadcast new feature creation to all sessions.
+
+        Args:
+            feature_id: New feature ID
+            agent_id: Agent creating the feature
+            session_id: Source session
+            payload: Feature details
+
+        Returns:
+            Number of clients notified
+        """
+        event = BroadcastEvent(
+            event_type=BroadcastEventType.FEATURE_CREATED,
+            resource_id=feature_id,
+            resource_type="feature",
+            agent_id=agent_id,
+            session_id=session_id,
+            payload=payload,
+        )
+
+        clients_notified = await self.websocket_manager.broadcast_to_all_sessions(
+            event.to_dict()
+        )
+
+        logger.info(
+            f"Broadcast new feature {feature_id} to {clients_notified} clients "
+            f"(agent={agent_id})"
+        )
+
+        return int(clients_notified)
+
+    async def broadcast_status_change(
+        self,
+        feature_id: str,
+        old_status: str,
+        new_status: str,
+        agent_id: str,
+        session_id: str,
+    ) -> int:
+        """
+        Broadcast feature status change across sessions.
+
+        Args:
+            feature_id: Feature being updated
+            old_status: Previous status
+            new_status: New status
+            agent_id: Agent making change
+            session_id: Source session
+
+        Returns:
+            Number of clients notified
+        """
+        return await self.broadcast_feature_update(
+            feature_id=feature_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            payload={
+                "change_type": "status",
+                "old_status": old_status,
+                "new_status": new_status,
+            },
+        )
+
+    async def broadcast_link_added(
+        self,
+        feature_id: str,
+        linked_feature_id: str,
+        link_type: str,  # "depends_on", "blocks", "related", etc.
+        agent_id: str,
+        session_id: str,
+    ) -> int:
+        """
+        Broadcast when feature links are added.
+
+        Args:
+            feature_id: Source feature
+            linked_feature_id: Target feature
+            link_type: Type of relationship
+            agent_id: Agent making change
+            session_id: Source session
+
+        Returns:
+            Number of clients notified
+        """
+        return await self.broadcast_feature_update(
+            feature_id=feature_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            payload={
+                "change_type": "link_added",
+                "linked_feature_id": linked_feature_id,
+                "link_type": link_type,
+            },
+        )
+
+    async def broadcast_track_update(
+        self,
+        track_id: str,
+        agent_id: str,
+        session_id: str,
+        payload: dict[str, Any],
+    ) -> int:
+        """
+        Broadcast track update to all sessions.
+
+        Args:
+            track_id: Track being updated
+            agent_id: Agent making change
+            session_id: Source session
+            payload: Update details
+
+        Returns:
+            Number of clients notified
+        """
+        event = BroadcastEvent(
+            event_type=BroadcastEventType.TRACK_UPDATED,
+            resource_id=track_id,
+            resource_type="track",
+            agent_id=agent_id,
+            session_id=session_id,
+            payload=payload,
+        )
+
+        clients_notified = await self.websocket_manager.broadcast_to_all_sessions(
+            event.to_dict()
+        )
+
+        logger.info(
+            f"Broadcast track {track_id} update to {clients_notified} clients "
+            f"(agent={agent_id})"
+        )
+
+        return int(clients_notified)
+
+    async def broadcast_spike_update(
+        self,
+        spike_id: str,
+        agent_id: str,
+        session_id: str,
+        payload: dict[str, Any],
+    ) -> int:
+        """
+        Broadcast spike update to all sessions.
+
+        Args:
+            spike_id: Spike being updated
+            agent_id: Agent making change
+            session_id: Source session
+            payload: Update details
+
+        Returns:
+            Number of clients notified
+        """
+        event = BroadcastEvent(
+            event_type=BroadcastEventType.SPIKE_UPDATED,
+            resource_id=spike_id,
+            resource_type="spike",
+            agent_id=agent_id,
+            session_id=session_id,
+            payload=payload,
+        )
+
+        clients_notified = await self.websocket_manager.broadcast_to_all_sessions(
+            event.to_dict()
+        )
+
+        logger.info(
+            f"Broadcast spike {spike_id} update to {clients_notified} clients "
+            f"(agent={agent_id})"
+        )
+
+        return int(clients_notified)

htmlgraph/api/broadcast_routes.py

@@ -0,0 +1,357 @@
+"""
+Broadcast API Routes - Cross-Session Synchronization
+
+REST API endpoints for broadcasting feature/track/spike updates
+across all active sessions.
+"""
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Header, HTTPException
+from pydantic import BaseModel
+
+from htmlgraph.api.broadcast import CrossSessionBroadcaster
+
+logger = logging.getLogger(__name__)
+
+
+class FeatureUpdateRequest(BaseModel):
+    """Request model for feature update broadcasts."""
+
+    title: str | None = None
+    status: str | None = None
+    description: str | None = None
+    tags: list[str] | None = None
+    priority: str | None = None
+
+
+class StatusChangeRequest(BaseModel):
+    """Request model for status change broadcasts."""
+
+    new_status: str
+
+
+class LinkAddRequest(BaseModel):
+    """Request model for link addition broadcasts."""
+
+    linked_feature_id: str
+    link_type: str
+
+
+def create_broadcast_router(
+    broadcaster: CrossSessionBroadcaster,
+    get_db: Any,
+) -> APIRouter:
+    """
+    Create broadcast API router with dependency injection.
+
+    Args:
+        broadcaster: CrossSessionBroadcaster instance
+        get_db: Database connection factory
+
+    Returns:
+        Configured APIRouter
+    """
+    router = APIRouter(prefix="/api/broadcast", tags=["broadcast"])
+
+    @router.post("/features/{feature_id}")
+    async def broadcast_feature_update(
+        feature_id: str,
+        update: FeatureUpdateRequest,
+        agent_id: str = Header(..., alias="X-Agent-ID"),
+        session_id: str = Header(..., alias="X-Session-ID"),
+    ) -> dict[str, Any]:
+        """
+        Broadcast feature update to all sessions.
+
+        Headers:
+        - X-Agent-ID: Agent making the change
+        - X-Session-ID: Source session ID
+
+        Body:
+        ```json
+        {
+            "title": "new title",
+            "status": "in_progress",
+            "description": "updated description",
+            "tags": ["api", "backend"],
+            "priority": "high"
+        }
+        ```
+
+        Returns:
+        ```json
+        {
+            "success": true,
+            "feature_id": "feat-123",
+            "clients_notified": 5,
+            "timestamp": "2025-01-01T12:00:00"
+        }
+        ```
+        """
+        # Validate feature exists
+        try:
+            db = await get_db()
+            try:
+                cursor = await db.execute(
+                    "SELECT id FROM nodes WHERE id = ? AND type = 'feature'",
+                    [feature_id],
+                )
+                if not await cursor.fetchone():
+                    raise HTTPException(
+                        status_code=404, detail=f"Feature {feature_id} not found"
+                    )
+            finally:
+                await db.close()
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Database error checking feature: {e}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+        # Build payload from request
+        payload = {}
+        if update.title is not None:
+            payload["title"] = update.title
+        if update.status is not None:
+            payload["status"] = update.status
+        if update.description is not None:
+            payload["description"] = update.description
+        if update.tags is not None:
+            payload["tags"] = ",".join(update.tags) if update.tags else ""
+        if update.priority is not None:
+            payload["priority"] = update.priority
+
+        # Broadcast update
+        clients_notified = await broadcaster.broadcast_feature_update(
+            feature_id=feature_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            payload=payload,
+        )
+
+        from datetime import datetime
+
+        return {
+            "success": True,
+            "feature_id": feature_id,
+            "clients_notified": clients_notified,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    @router.post("/features/{feature_id}/status")
+    async def update_feature_status(
+        feature_id: str,
+        request: StatusChangeRequest,
+        agent_id: str = Header(..., alias="X-Agent-ID"),
+        session_id: str = Header(..., alias="X-Session-ID"),
+    ) -> dict[str, Any]:
+        """
+        Update feature status and broadcast to all sessions.
+
+        Valid statuses: todo, in_progress, blocked, done
+        """
+        # Validate status
+        valid_statuses = ["todo", "in_progress", "blocked", "done"]
+        if request.new_status not in valid_statuses:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid status: {request.new_status}. Must be one of {valid_statuses}",
+            )
+
+        # Get current status
+        try:
+            db = await get_db()
+            try:
+                cursor = await db.execute(
+                    "SELECT status FROM nodes WHERE id = ? AND type = 'feature'",
+                    [feature_id],
+                )
+                row = await cursor.fetchone()
+                if not row:
+                    raise HTTPException(
+                        status_code=404, detail=f"Feature {feature_id} not found"
+                    )
+
+                old_status = row[0] if row[0] else "todo"
+            finally:
+                await db.close()
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Database error fetching feature status: {e}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+        # Broadcast status change
+        clients_notified = await broadcaster.broadcast_status_change(
+            feature_id=feature_id,
+            old_status=old_status,
+            new_status=request.new_status,
+            agent_id=agent_id,
+            session_id=session_id,
+        )
+
+        from datetime import datetime
+
+        return {
+            "success": True,
+            "feature_id": feature_id,
+            "old_status": old_status,
+            "new_status": request.new_status,
+            "clients_notified": clients_notified,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    @router.post("/features/{feature_id}/links")
+    async def add_feature_link(
+        feature_id: str,
+        request: LinkAddRequest,
+        agent_id: str = Header(..., alias="X-Agent-ID"),
+        session_id: str = Header(..., alias="X-Session-ID"),
+    ) -> dict[str, Any]:
+        """
+        Add feature link and broadcast to all sessions.
+
+        Valid link types: depends_on, blocks, related
+        """
+        # Validate link type
+        valid_link_types = ["depends_on", "blocks", "related"]
+        if request.link_type not in valid_link_types:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid link type: {request.link_type}. Must be one of {valid_link_types}",
+            )
+
+        # Validate both features exist
+        try:
+            db = await get_db()
+            try:
+                cursor = await db.execute(
+                    "SELECT id FROM nodes WHERE id IN (?, ?) AND type = 'feature'",
+                    [feature_id, request.linked_feature_id],
+                )
+                rows = await cursor.fetchall()
+                if len(rows) != 2:
+                    raise HTTPException(
+                        status_code=404, detail="One or both features not found"
+                    )
+            finally:
+                await db.close()
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Database error validating features: {e}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+        # Broadcast link addition
+        clients_notified = await broadcaster.broadcast_link_added(
+            feature_id=feature_id,
+            linked_feature_id=request.linked_feature_id,
+            link_type=request.link_type,
+            agent_id=agent_id,
+            session_id=session_id,
+        )
+
+        from datetime import datetime
+
+        return {
+            "success": True,
+            "feature_id": feature_id,
+            "linked_feature_id": request.linked_feature_id,
+            "link_type": request.link_type,
+            "clients_notified": clients_notified,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    @router.post("/tracks/{track_id}")
+    async def broadcast_track_update(
+        track_id: str,
+        update: dict[str, Any],
+        agent_id: str = Header(..., alias="X-Agent-ID"),
+        session_id: str = Header(..., alias="X-Session-ID"),
+    ) -> dict[str, Any]:
+        """Broadcast track update to all sessions."""
+        # Validate track exists
+        try:
+            db = await get_db()
+            try:
+                cursor = await db.execute(
+                    "SELECT id FROM nodes WHERE id = ? AND type = 'track'",
+                    [track_id],
+                )
+                if not await cursor.fetchone():
+                    raise HTTPException(
+                        status_code=404, detail=f"Track {track_id} not found"
+                    )
+            finally:
+                await db.close()
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Database error checking track: {e}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+        # Broadcast update
+        clients_notified = await broadcaster.broadcast_track_update(
+            track_id=track_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            payload=update,
+        )
+
+        from datetime import datetime
+
+        return {
+            "success": True,
+            "track_id": track_id,
+            "clients_notified": clients_notified,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    @router.post("/spikes/{spike_id}")
+    async def broadcast_spike_update(
+        spike_id: str,
+        update: dict[str, Any],
+        agent_id: str = Header(..., alias="X-Agent-ID"),
+        session_id: str = Header(..., alias="X-Session-ID"),
+    ) -> dict[str, Any]:
+        """Broadcast spike update to all sessions."""
+        # Validate spike exists
+        try:
+            db = await get_db()
+            try:
+                cursor = await db.execute(
+                    "SELECT id FROM nodes WHERE id = ? AND type = 'spike'",
+                    [spike_id],
+                )
+                if not await cursor.fetchone():
+                    raise HTTPException(
+                        status_code=404, detail=f"Spike {spike_id} not found"
+                    )
+            finally:
+                await db.close()
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Database error checking spike: {e}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+        # Broadcast update
+        clients_notified = await broadcaster.broadcast_spike_update(
+            spike_id=spike_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            payload=update,
+        )
+
+        from datetime import datetime
+
+        return {
+            "success": True,
+            "spike_id": spike_id,
+            "clients_notified": clients_notified,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    return router