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

htmlgraph/api/websocket.py

@@ -90,6 +90,7 @@ class WebSocketClient:
 
     websocket: WebSocket
     client_id: str
+    session_id: str  # Session this client belongs to
     subscription_filter: EventSubscriptionFilter
     connected_at: datetime = field(default_factory=datetime.now)
     events_sent: int = 0
@@ -189,8 +190,9 @@ class WebSocketManager:
         self.event_batch_window_ms = event_batch_window_ms
         self.poll_interval_ms = poll_interval_ms / 1000.0  # Convert to seconds
 
-        # Active connections: {session_id: {client_id: WebSocketClient}}
-        self.connections: dict[str, dict[str, WebSocketClient]] = {}
+        # Active connections: {client_id: WebSocketClient}
+        # Flattened structure enables efficient cross-session broadcasting
+        self.connections: dict[str, WebSocketClient] = {}
 
         # Event batchers per session: {session_id: EventBatcher}
         self.batchers: dict[str, EventBatcher] = {}
@@ -227,7 +229,7 @@ class WebSocketManager:
             await websocket.accept()
 
             # Check max clients per session
-            session_clients = self.connections.get(session_id, {})
+            session_clients = await self.get_session_clients(session_id)
             if len(session_clients) >= self.max_clients_per_session:
                 logger.warning(
                     f"Session {session_id} has max clients ({self.max_clients_per_session})"
@@ -243,13 +245,12 @@ class WebSocketManager:
             client = WebSocketClient(
                 websocket=websocket,
                 client_id=client_id,
+                session_id=session_id,
                 subscription_filter=subscription_filter,
             )
 
-            # Add to connections
-            if session_id not in self.connections:
-                self.connections[session_id] = {}
-            self.connections[session_id][client_id] = client
+            # Add to flat connections structure
+            self.connections[client_id] = client
 
             # Create batcher for session if needed
             if session_id not in self.batchers:
@@ -260,7 +261,8 @@ class WebSocketManager:
 
             # Update metrics
             self.metrics["total_connections"] += 1
-            self.metrics["active_sessions"] = len(self.connections)
+            active_sessions = await self.get_active_sessions()
+            self.metrics["active_sessions"] = len(active_sessions)
 
             logger.info(
                 f"WebSocket client connected: session={session_id}, client={client_id}"
@@ -279,24 +281,48 @@ class WebSocketManager:
             session_id: Session ID
             client_id: Client ID to disconnect
         """
-        if session_id not in self.connections:
+        if client_id not in self.connections:
             return
 
-        if client_id in self.connections[session_id]:
-            client = self.connections[session_id][client_id]
-            del self.connections[session_id][client_id]
+        client = self.connections[client_id]
+        del self.connections[client_id]
 
-            # Update metrics
-            if not self.connections[session_id]:
-                del self.connections[session_id]
-                if session_id in self.batchers:
-                    del self.batchers[session_id]
+        # Check if this was the last client for the session
+        session_clients = await self.get_session_clients(session_id)
+        if not session_clients:
+            # Clean up session batcher
+            if session_id in self.batchers:
+                del self.batchers[session_id]
 
-            self.metrics["active_sessions"] = len(self.connections)
-            logger.info(
-                f"WebSocket client disconnected: session={session_id}, client={client_id}, "
-                f"events_sent={client.events_sent}"
-            )
+        # Update metrics
+        active_sessions = await self.get_active_sessions()
+        self.metrics["active_sessions"] = len(active_sessions)
+
+        logger.info(
+            f"WebSocket client disconnected: session={session_id}, client={client_id}, "
+            f"events_sent={client.events_sent}"
+        )
+
+    async def get_session_clients(self, session_id: str) -> list[WebSocketClient]:
+        """
+        Get all clients for a specific session.
+
+        Args:
+            session_id: Session ID to filter by
+
+        Returns:
+            List of clients belonging to the session
+        """
+        return [c for c in self.connections.values() if c.session_id == session_id]
+
+    async def get_active_sessions(self) -> set[str]:
+        """
+        Get all active session IDs.
+
+        Returns:
+            Set of session IDs with active connections
+        """
+        return {c.session_id for c in self.connections.values()}
 
     async def stream_events(
         self,
@@ -318,14 +344,11 @@ class WebSocketManager:
             client_id: Client ID
             get_db: Async function to get database connection
         """
-        if (
-            session_id not in self.connections
-            or client_id not in self.connections[session_id]
-        ):
-            logger.warning(f"Client not found: {session_id}/{client_id}")
+        if client_id not in self.connections:
+            logger.warning(f"Client not found: {client_id}")
             return
 
-        client = self.connections[session_id][client_id]
+        client = self.connections[client_id]
         last_timestamp = datetime.now().isoformat()
         poll_interval = self.poll_interval_ms
         consecutive_empty_polls = 0
@@ -487,11 +510,21 @@ class WebSocketManager:
         Returns:
             Number of clients that received the event
         """
-        if session_id not in self.connections:
-            return 0
+        return await self.broadcast_to_session(session_id, event)
+
+    async def broadcast_to_session(self, session_id: str, event: dict[str, Any]) -> int:
+        """
+        Broadcast event to all clients in a specific session.
+
+        Args:
+            session_id: Session to broadcast to
+            event: Event data
 
+        Returns:
+            Number of clients that received the event
+        """
         sent_count = 0
-        session_clients = list(self.connections[session_id].values())
+        session_clients = await self.get_session_clients(session_id)
 
         for client in session_clients:
             if client.subscription_filter.matches_event(event):
@@ -510,12 +543,56 @@ class WebSocketManager:
 
         return sent_count
 
+    async def broadcast_to_all_sessions(self, event: dict[str, Any]) -> int:
+        """
+        Broadcast event to all connected clients across all sessions.
+
+        Enables cross-session features like:
+        - Global notifications
+        - System-wide alerts
+        - Cross-agent coordination
+
+        Args:
+            event: Event data to broadcast
+
+        Returns:
+            Number of clients that received the event
+        """
+        sent_count = 0
+
+        for client in list(self.connections.values()):
+            if client.subscription_filter.matches_event(event):
+                try:
+                    await client.websocket.send_json(
+                        {
+                            "type": "event",
+                            "timestamp": datetime.now().isoformat(),
+                            **event,
+                        }
+                    )
+                    sent_count += 1
+                    client.events_sent += 1
+                except Exception as e:
+                    logger.error(f"Broadcast error to {client.client_id}: {e}")
+
+        return sent_count
+
     def get_session_metrics(self, session_id: str) -> dict[str, Any]:
         """Get metrics for a session."""
-        if session_id not in self.connections:
+        # Use asyncio.run to call async method in sync context
+        import asyncio
+
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        clients = loop.run_until_complete(self.get_session_clients(session_id))
+
+        if not clients:
             return {}
 
-        clients = self.connections[session_id].values()
         return {
             "session_id": session_id,
             "connected_clients": len(clients),
@@ -531,8 +608,6 @@ class WebSocketManager:
         """Get global WebSocket metrics."""
         return {
             **self.metrics,
-            "active_sessions": len(self.connections),
-            "total_connected_clients": sum(
-                len(clients) for clients in self.connections.values()
-            ),
+            "active_sessions": self.metrics["active_sessions"],
+            "total_connected_clients": len(self.connections),
         }

htmlgraph/broadcast_integration.py

@@ -0,0 +1,227 @@
+"""
+Broadcast Integration Helper - SDK to Broadcast Bridge
+
+Provides helper functions to integrate broadcasting with SDK operations.
+Handles the bridge between synchronous SDK calls and async broadcast operations.
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def get_or_create_event_loop() -> asyncio.AbstractEventLoop:
+    """Get existing event loop or create new one if none exists."""
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        # No event loop running, create a new one
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_closed():
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+            return loop
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            return loop
+
+
+def broadcast_feature_save(
+    feature_id: str,
+    agent_id: str,
+    session_id: str,
+    payload: dict[str, Any],
+    is_new: bool = False,
+) -> None:
+    """
+    Broadcast feature save operation to all sessions.
+
+    This is a synchronous wrapper that can be called from SDK save() methods.
+    It handles async event loop creation and broadcasting.
+
+    Args:
+        feature_id: Feature being saved
+        agent_id: Agent making the change
+        session_id: Source session ID
+        payload: Feature data (title, status, description, etc.)
+        is_new: True if creating new feature, False if updating
+    """
+    try:
+        # Import here to avoid circular dependencies
+        from pathlib import Path
+
+        from htmlgraph.api.broadcast import CrossSessionBroadcaster
+        from htmlgraph.api.websocket import WebSocketManager
+
+        # Get database path
+        db_path = str(Path.home() / ".htmlgraph" / "htmlgraph.db")
+
+        # Create WebSocketManager and Broadcaster instances
+        # Note: These are lightweight, stateless for broadcasting
+        websocket_manager = WebSocketManager(db_path)
+        broadcaster = CrossSessionBroadcaster(websocket_manager, db_path)
+
+        # Determine event type
+        event_type = "created" if is_new else "updated"
+        payload["event_type"] = event_type
+
+        # Run async broadcast in event loop
+        loop = get_or_create_event_loop()
+
+        if loop.is_running():
+            # We're already in an async context, schedule task
+            asyncio.create_task(
+                broadcaster.broadcast_feature_update(
+                    feature_id=feature_id,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    payload=payload,
+                )
+            )
+            # Don't wait for completion to avoid blocking
+            logger.debug(
+                f"Scheduled broadcast task for feature {feature_id} (async context)"
+            )
+        else:
+            # Not in async context, run until complete
+            clients_notified = loop.run_until_complete(
+                broadcaster.broadcast_feature_update(
+                    feature_id=feature_id,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    payload=payload,
+                )
+            )
+            logger.info(
+                f"Broadcast feature {feature_id} {event_type} to {clients_notified} clients"
+            )
+
+    except Exception as e:
+        # Never fail the save due to broadcast error
+        logger.warning(f"Failed to broadcast feature save: {e}")
+
+
+def broadcast_status_change(
+    feature_id: str,
+    old_status: str,
+    new_status: str,
+    agent_id: str,
+    session_id: str,
+) -> None:
+    """
+    Broadcast feature status change to all sessions.
+
+    Synchronous wrapper for async broadcast operation.
+
+    Args:
+        feature_id: Feature being updated
+        old_status: Previous status
+        new_status: New status
+        agent_id: Agent making change
+        session_id: Source session
+    """
+    try:
+        from pathlib import Path
+
+        from htmlgraph.api.broadcast import CrossSessionBroadcaster
+        from htmlgraph.api.websocket import WebSocketManager
+
+        db_path = str(Path.home() / ".htmlgraph" / "htmlgraph.db")
+        websocket_manager = WebSocketManager(db_path)
+        broadcaster = CrossSessionBroadcaster(websocket_manager, db_path)
+
+        loop = get_or_create_event_loop()
+
+        if loop.is_running():
+            asyncio.create_task(
+                broadcaster.broadcast_status_change(
+                    feature_id=feature_id,
+                    old_status=old_status,
+                    new_status=new_status,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                )
+            )
+            logger.debug(f"Scheduled status change broadcast for {feature_id}")
+        else:
+            clients_notified = loop.run_until_complete(
+                broadcaster.broadcast_status_change(
+                    feature_id=feature_id,
+                    old_status=old_status,
+                    new_status=new_status,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                )
+            )
+            logger.info(
+                f"Broadcast status change for {feature_id}: {old_status} → {new_status} "
+                f"to {clients_notified} clients"
+            )
+
+    except Exception as e:
+        logger.warning(f"Failed to broadcast status change: {e}")
+
+
+def broadcast_link_added(
+    feature_id: str,
+    linked_feature_id: str,
+    link_type: str,
+    agent_id: str,
+    session_id: str,
+) -> None:
+    """
+    Broadcast feature link addition to all sessions.
+
+    Synchronous wrapper for async broadcast operation.
+
+    Args:
+        feature_id: Source feature
+        linked_feature_id: Target feature
+        link_type: Type of relationship
+        agent_id: Agent making change
+        session_id: Source session
+    """
+    try:
+        from pathlib import Path
+
+        from htmlgraph.api.broadcast import CrossSessionBroadcaster
+        from htmlgraph.api.websocket import WebSocketManager
+
+        db_path = str(Path.home() / ".htmlgraph" / "htmlgraph.db")
+        websocket_manager = WebSocketManager(db_path)
+        broadcaster = CrossSessionBroadcaster(websocket_manager, db_path)
+
+        loop = get_or_create_event_loop()
+
+        if loop.is_running():
+            asyncio.create_task(
+                broadcaster.broadcast_link_added(
+                    feature_id=feature_id,
+                    linked_feature_id=linked_feature_id,
+                    link_type=link_type,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                )
+            )
+            logger.debug(f"Scheduled link broadcast for {feature_id}")
+        else:
+            clients_notified = loop.run_until_complete(
+                broadcaster.broadcast_link_added(
+                    feature_id=feature_id,
+                    linked_feature_id=linked_feature_id,
+                    link_type=link_type,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                )
+            )
+            logger.info(
+                f"Broadcast link addition for {feature_id} → {linked_feature_id} "
+                f"({link_type}) to {clients_notified} clients"
+            )
+
+    except Exception as e:
+        logger.warning(f"Failed to broadcast link addition: {e}")

htmlgraph/cli_commands/sync.py

@@ -0,0 +1,207 @@
+"""
+CLI commands for Git-based sync management.
+
+Provides commands to start/stop background sync, trigger manual operations,
+and check sync status.
+"""
+
+import asyncio
+from pathlib import Path
+
+import click
+
+from htmlgraph.sync import GitSyncManager, SyncConfig, SyncStrategy
+
+
+@click.group()
+def sync() -> None:
+    """Git-based multi-device sync commands."""
+    pass
+
+
+@sync.command()
+@click.option(
+    "--push-interval",
+    type=int,
+    default=300,
+    help="Push interval in seconds (default: 300 = 5 min)",
+)
+@click.option(
+    "--pull-interval",
+    type=int,
+    default=60,
+    help="Pull interval in seconds (default: 60 = 1 min)",
+)
+@click.option(
+    "--strategy",
+    type=click.Choice(["auto_merge", "abort_on_conflict", "ours", "theirs"]),
+    default="auto_merge",
+    help="Conflict resolution strategy",
+)
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True),
+    default=".",
+    help="Git repository root path",
+)
+def start(
+    push_interval: int, pull_interval: int, strategy: str, repo_root: str
+) -> None:
+    """Start background sync service."""
+    config = SyncConfig(
+        push_interval_seconds=push_interval,
+        pull_interval_seconds=pull_interval,
+        conflict_strategy=SyncStrategy(strategy),
+    )
+
+    manager = GitSyncManager(repo_root, config)
+
+    click.echo("Starting background sync service...")
+    click.echo(f"  Push interval: {push_interval}s")
+    click.echo(f"  Pull interval: {pull_interval}s")
+    click.echo(f"  Conflict strategy: {strategy}")
+    click.echo(f"  Repository: {Path(repo_root).absolute()}")
+
+    try:
+        asyncio.run(manager.start_background_sync())
+    except KeyboardInterrupt:
+        click.echo("\nStopping background sync...")
+        asyncio.run(manager.stop_background_sync())
+
+
+@sync.command()
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True),
+    default=".",
+    help="Git repository root path",
+)
+def push(repo_root: str) -> None:
+    """Manually push changes to remote."""
+    manager = GitSyncManager(repo_root)
+
+    click.echo("Pushing changes to remote...")
+
+    async def do_push() -> None:
+        result = await manager.push(force=True)
+        click.echo(f"Status: {result.status.value}")
+        click.echo(f"Files changed: {result.files_changed}")
+        click.echo(f"Message: {result.message}")
+        if result.conflicts:
+            click.echo(f"Conflicts: {', '.join(result.conflicts)}")
+
+    asyncio.run(do_push())
+
+
+@sync.command()
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True),
+    default=".",
+    help="Git repository root path",
+)
+def pull(repo_root: str) -> None:
+    """Manually pull changes from remote."""
+    manager = GitSyncManager(repo_root)
+
+    click.echo("Pulling changes from remote...")
+
+    async def do_pull() -> None:
+        result = await manager.pull(force=True)
+        click.echo(f"Status: {result.status.value}")
+        click.echo(f"Message: {result.message}")
+        if result.conflicts:
+            click.echo(f"Conflicts: {', '.join(result.conflicts)}")
+
+    asyncio.run(do_pull())
+
+
+@sync.command()
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True),
+    default=".",
+    help="Git repository root path",
+)
+@click.option(
+    "--limit",
+    type=int,
+    default=10,
+    help="Number of recent operations to show",
+)
+def status(repo_root: str, limit: int) -> None:
+    """Show sync status and recent history."""
+    manager = GitSyncManager(repo_root)
+
+    status_data = manager.get_status()
+    history = manager.get_sync_history(limit)
+
+    click.echo("Sync Status:")
+    click.echo(f"  Current status: {status_data['status']}")
+    click.echo(f"  Last push: {status_data['last_push'] or 'Never'}")
+    click.echo(f"  Last pull: {status_data['last_pull'] or 'Never'}")
+    click.echo("\nConfiguration:")
+    click.echo(f"  Remote: {status_data['config']['remote']}")
+    click.echo(f"  Branch: {status_data['config']['branch']}")
+    click.echo(f"  Push interval: {status_data['config']['push_interval']}s")
+    click.echo(f"  Pull interval: {status_data['config']['pull_interval']}s")
+    click.echo(f"  Conflict strategy: {status_data['config']['conflict_strategy']}")
+
+    if history:
+        click.echo(f"\nRecent Operations (last {len(history)}):")
+        for entry in history:
+            click.echo(
+                f"  [{entry['operation']}] {entry['status']} - {entry['message']}"
+            )
+
+
+@sync.command()
+@click.option(
+    "--repo-root",
+    type=click.Path(exists=True),
+    default=".",
+    help="Git repository root path",
+)
+@click.option(
+    "--push-interval",
+    type=int,
+    help="New push interval in seconds",
+)
+@click.option(
+    "--pull-interval",
+    type=int,
+    help="New pull interval in seconds",
+)
+@click.option(
+    "--strategy",
+    type=click.Choice(["auto_merge", "abort_on_conflict", "ours", "theirs"]),
+    help="New conflict resolution strategy",
+)
+def configure(
+    repo_root: str,
+    push_interval: int | None,
+    pull_interval: int | None,
+    strategy: str | None,
+) -> None:
+    """Update sync configuration."""
+    manager = GitSyncManager(repo_root)
+
+    if push_interval:
+        manager.config.push_interval_seconds = push_interval
+        click.echo(f"Push interval updated to {push_interval}s")
+
+    if pull_interval:
+        manager.config.pull_interval_seconds = pull_interval
+        click.echo(f"Pull interval updated to {pull_interval}s")
+
+    if strategy:
+        manager.config.conflict_strategy = SyncStrategy(strategy)
+        click.echo(f"Conflict strategy updated to {strategy}")
+
+    if not any([push_interval, pull_interval, strategy]):
+        click.echo("No configuration changes specified")
+        click.echo("Use --push-interval, --pull-interval, or --strategy")
+
+
+if __name__ == "__main__":
+    sync()