htmlgraph 0.24.2__py3-none-any.whl → 0.26.1__py3-none-any.whl

htmlgraph/cli_commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations."""

htmlgraph/cli_commands/feature.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+from rich.table import Table
+
+from htmlgraph.cli_framework import BaseCommand, CommandError, CommandResult
+
+_console = Console()
+
+
+class FeatureCreateCommand(BaseCommand):
+    def __init__(
+        self,
+        *,
+        collection: str,
+        title: str,
+        description: str,
+        priority: str,
+        steps: Iterable[str] | None,
+        track_id: str | None = None,
+    ) -> None:
+        super().__init__()
+        self.collection = collection
+        self.title = title
+        self.description = description
+        self.priority = priority
+        self.steps = list(steps) if steps else []
+        self.track_id = track_id
+
+    def execute(self) -> CommandResult:
+        sdk = self.get_sdk()
+
+        # Determine track_id for feature creation
+        track_id = self.track_id
+
+        # Only enforce track selection for main features collection
+        if self.collection == "features":
+            if not track_id:
+                # Get available tracks
+                try:
+                    tracks = sdk.tracks.all()
+                    if not tracks:
+                        raise CommandError(
+                            "No tracks found. Create a track first:\n"
+                            "  uv run htmlgraph track new 'Track Title'"
+                        )
+
+                    if len(tracks) == 1:
+                        # Auto-select if only one track exists
+                        track_id = tracks[0].id
+                        _console.print(
+                            f"[dim]Auto-selected track: {tracks[0].title}[/dim]"
+                        )
+                    else:
+                        # Interactive selection
+                        _console.print("[bold]Available Tracks:[/bold]")
+                        for i, track in enumerate(tracks, 1):
+                            _console.print(f"  {i}. {track.title} ({track.id})")
+
+                        selection = Prompt.ask(
+                            "Select track",
+                            choices=[str(i) for i in range(1, len(tracks) + 1)],
+                        )
+                        track_id = tracks[int(selection) - 1].id
+                except Exception as e:
+                    raise CommandError(f"Failed to get available tracks: {e}")
+
+            builder = sdk.features.create(
+                title=self.title,
+                description=self.description,
+                priority=self.priority,
+            )
+            if self.steps:
+                builder.add_steps(self.steps)
+            if track_id:
+                builder.set_track(track_id)
+            node = builder.save()
+        else:
+            node = sdk.session_manager.create_feature(
+                title=self.title,
+                collection=self.collection,
+                description=self.description,
+                priority=self.priority,
+                steps=self.steps,
+                agent=self.agent,
+            )
+
+        # Format output with Rich
+        table = Table(show_header=False, box=None)
+        table.add_column(style="bold cyan")
+        table.add_column()
+
+        table.add_row("Created:", f"[green]{node.id}[/green]")
+        table.add_row("Title:", f"[yellow]{node.title}[/yellow]")
+        table.add_row("Status:", f"[blue]{node.status}[/blue]")
+        if node.track_id:
+            table.add_row("Track:", f"[cyan]{node.track_id}[/cyan]")
+        table.add_row(
+            "Path:", f"[dim]{self.graph_dir}/{self.collection}/{node.id}.html[/dim]"
+        )
+
+        # Format as Rich panel for text output
+        text = [
+            f"Created: {node.id}",
+            f"  Title: {node.title}",
+            f"  Status: {node.status}",
+        ]
+        if node.track_id:
+            text.append(f"  Track: {node.track_id}")
+        text.append(f"  Path: {self.graph_dir}/{self.collection}/{node.id}.html")
+
+        return CommandResult(data=node, text=text)
+
+
+class FeatureStartCommand(BaseCommand):
+    def __init__(self, *, collection: str, feature_id: str) -> None:
+        super().__init__()
+        self.collection = collection
+        self.feature_id = feature_id
+
+    def execute(self) -> CommandResult:
+        sdk = self.get_sdk()
+        collection = getattr(sdk, self.collection, None)
+
+        if not collection:
+            raise CommandError(f"Collection '{self.collection}' not found in SDK.")
+
+        node = collection.start(self.feature_id)
+        if node is None:
+            raise CommandError(
+                f"Feature '{self.feature_id}' not found in {self.collection}."
+            )
+
+        status = sdk.session_manager.get_status()
+
+        # Format output with Rich
+        table = Table(show_header=False, box=None)
+        table.add_column(style="bold cyan")
+        table.add_column()
+
+        table.add_row("Started:", f"[green]{node.id}[/green]")
+        table.add_row("Title:", f"[yellow]{node.title}[/yellow]")
+        table.add_row("Status:", f"[blue]{node.status}[/blue]")
+        wip_color = "red" if status["wip_count"] >= status["wip_limit"] else "green"
+        table.add_row(
+            "WIP:",
+            f"[{wip_color}]{status['wip_count']}/{status['wip_limit']}[/{wip_color}]",
+        )
+
+        text = [
+            f"Started: {node.id}",
+            f"  Title: {node.title}",
+            f"  Status: {node.status}",
+            f"  WIP: {status['wip_count']}/{status['wip_limit']}",
+        ]
+        return CommandResult(data=node, text=text)
+
+
+class FeatureCompleteCommand(BaseCommand):
+    def __init__(self, *, collection: str, feature_id: str) -> None:
+        super().__init__()
+        self.collection = collection
+        self.feature_id = feature_id
+
+    def execute(self) -> CommandResult:
+        sdk = self.get_sdk()
+        collection = getattr(sdk, self.collection, None)
+
+        if not collection:
+            raise CommandError(f"Collection '{self.collection}' not found in SDK.")
+
+        node = collection.complete(self.feature_id)
+        if node is None:
+            raise CommandError(
+                f"Feature '{self.feature_id}' not found in {self.collection}."
+            )
+
+        # Format output with Rich
+        panel = Panel(
+            f"[bold green]✓ Completed[/bold green]\n"
+            f"[cyan]{node.id}[/cyan]\n"
+            f"[yellow]{node.title}[/yellow]",
+            border_style="green",
+        )
+        _console.print(panel)
+
+        text = [
+            f"Completed: {node.id}",
+            f"  Title: {node.title}",
+        ]
+        return CommandResult(data=node, text=text)

htmlgraph/cli_framework.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import TYPE_CHECKING, Any, Protocol
+
+from rich.console import Console
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+_console = Console()
+
+
+class CommandError(Exception):
+    """User-facing CLI error with an exit code."""
+
+    def __init__(self, message: str, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+@dataclass
+class CommandResult:
+    data: Any = None
+    text: str | Iterable[str] | None = None
+    json_data: Any | None = None
+
+
+class Formatter(Protocol):
+    def output(self, result: CommandResult) -> None: ...
+
+
+def _serialize_json(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if hasattr(value, "model_dump") and callable(getattr(value, "model_dump")):
+        return _serialize_json(value.model_dump())
+    if hasattr(value, "to_dict") and callable(getattr(value, "to_dict")):
+        return _serialize_json(value.to_dict())
+    if isinstance(value, dict):
+        return {key: _serialize_json(val) for key, val in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_serialize_json(item) for item in value]
+    return value
+
+
+class JsonFormatter:
+    def output(self, result: CommandResult) -> None:
+        payload = result.json_data if result.json_data is not None else result.data
+        _console.print(json.dumps(_serialize_json(payload), indent=2))
+
+
+class TextFormatter:
+    def output(self, result: CommandResult) -> None:
+        if result.text is None:
+            if result.data is not None:
+                _console.print(result.data)
+            return
+        if isinstance(result.text, str):
+            _console.print(result.text)
+            return
+        _console.print("\n".join(str(line) for line in result.text))
+
+
+def get_formatter(format_name: str) -> Formatter:
+    if format_name == "json":
+        return JsonFormatter()
+    if format_name in ("text", "plain", ""):
+        return TextFormatter()
+    raise CommandError(f"Unknown output format '{format_name}'")
+
+
+class BaseCommand:
+    def __init__(self) -> None:
+        self.graph_dir: str | None = None
+        self.agent: str | None = None
+        self._sdk: SDK | None = None
+
+    def validate(self) -> None:
+        return None
+
+    def execute(self) -> CommandResult:
+        raise NotImplementedError
+
+    def get_sdk(self) -> Any:
+        if self.graph_dir is None:
+            raise CommandError("Missing graph directory for command execution.")
+        if self._sdk is None:
+            from htmlgraph.sdk import SDK
+
+            self._sdk = SDK(directory=self.graph_dir, agent=self.agent)
+        return self._sdk
+
+    def run(self, *, graph_dir: str, agent: str | None, output_format: str) -> None:
+        self.graph_dir = graph_dir
+        self.agent = agent
+        try:
+            self.validate()
+            result = self.execute()
+            formatter = get_formatter(output_format)
+            formatter.output(result)
+        except CommandError as exc:
+            error_console = Console(file=sys.stderr)
+            error_console.print(f"[red]Error: {exc}[/red]")
+            sys.exit(exc.exit_code)
+        except ValueError as exc:
+            error_console = Console(file=sys.stderr)
+            error_console.print(f"[red]Error: {exc}[/red]")
+            sys.exit(1)

htmlgraph/collections/__init__.py

@@ -15,6 +15,7 @@ from htmlgraph.collections.metric import MetricCollection
 from htmlgraph.collections.pattern import PatternCollection
 from htmlgraph.collections.phase import PhaseCollection
 from htmlgraph.collections.spike import SpikeCollection
+from htmlgraph.collections.task_delegation import TaskDelegationCollection
 from htmlgraph.collections.todo import TodoCollection
 
 __all__ = [
@@ -29,4 +30,5 @@ __all__ = [
     "InsightCollection",
     "MetricCollection",
     "TodoCollection",
+    "TaskDelegationCollection",
 ]

htmlgraph/collections/base.py

@@ -525,6 +525,27 @@ class BaseCollection(Generic[CollectionT]):
                 node.updated = datetime.now()
                 graph.update(node)
                 results["success_count"] += 1
+
+                # Log completion event to SQLite
+                try:
+                    self._sdk._log_event(
+                        event_type="tool_call",
+                        tool_name="SDK.mark_done",
+                        input_summary=f"Mark {self._node_type} done: {node_id}",
+                        output_summary=f"Marked {node_id} as done",
+                        context={
+                            "collection": self._collection_name,
+                            "node_id": node_id,
+                            "node_type": self._node_type,
+                            "title": node.title,
+                        },
+                        cost_tokens=25,
+                    )
+                except Exception as e:
+                    import logging
+
+                    logging.debug(f"Event logging failed for mark_done: {e}")
+
             except Exception as e:
                 results["failed_ids"].append(node_id)
                 results["warnings"].append(f"Failed to mark {node_id}: {str(e)}")

htmlgraph/collections/session.py

@@ -0,0 +1,189 @@
+"""
+SessionCollection - Session state and management interface.
+
+Provides methods to:
+- Get current session state automatically
+- Set up environment variables automatically
+- Track session metadata
+- Detect post-compact sessions
+
+Integration with SessionStart hook:
+    sdk = SDK()
+    state = sdk.sessions.get_current_state()
+    sdk.sessions.setup_environment_variables(state)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from htmlgraph.collections.base import BaseCollection
+from htmlgraph.session_state import SessionState, SessionStateManager
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+
+class SessionCollection(BaseCollection):
+    """
+    Collection interface for session state management.
+
+    Extends BaseCollection with session-specific state management operations.
+
+    Provides:
+    - Automatic session state detection (post-compact, delegation status)
+    - Environment variable setup (CLAUDE_SESSION_ID, CLAUDE_DELEGATION_ENABLED, etc.)
+    - Session metadata recording and retrieval
+    - Compact detection
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> state = sdk.sessions.get_current_state()
+        >>> sdk.sessions.setup_environment_variables(state)
+        # All environment variables automatically set
+    """
+
+    _collection_name = "sessions"
+    _node_type = "session"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize SessionCollection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "sessions", "session")
+        self._state_manager = SessionStateManager(sdk._directory)
+
+    def get_current_state(self) -> SessionState:
+        """
+        Get current session state with automatic detection.
+
+        Automatically detects:
+        - Current session ID
+        - Session source (startup, resume, compact, clear)
+        - Post-compact status
+        - Delegation enable/disable
+        - Session validity
+
+        Returns:
+            SessionState dict with:
+            - session_id: Current session identifier
+            - session_source: "startup", "resume", "compact", "clear"
+            - is_post_compact: True if this is post-compact session
+            - previous_session_id: Previous session ID if available
+            - delegation_enabled: Should delegation be active
+            - prompt_injected: Was orchestrator prompt injected
+            - session_valid: Is session valid for tracking
+            - timestamp: Current UTC timestamp
+            - compact_metadata: Compact detection details
+
+        Example:
+            >>> sdk = SDK()
+            >>> state = sdk.sessions.get_current_state()
+            >>> print(f"Session: {state['session_id']}")
+            >>> print(f"Post-compact: {state['is_post_compact']}")
+            >>> print(f"Delegation enabled: {state['delegation_enabled']}")
+        """
+        return self._state_manager.get_current_state()
+
+    def setup_environment_variables(
+        self,
+        session_state: SessionState | None = None,
+        auto_detect_compact: bool = True,
+    ) -> dict[str, str]:
+        """
+        Automatically set up environment variables for session state.
+
+        Sets up environment variables that persist across context boundaries:
+        - CLAUDE_SESSION_ID: Current session identifier
+        - CLAUDE_SESSION_SOURCE: "startup|resume|compact|clear"
+        - CLAUDE_SESSION_COMPACTED: "true|false"
+        - CLAUDE_DELEGATION_ENABLED: "true|false"
+        - CLAUDE_PREVIOUS_SESSION_ID: Previous session ID
+        - CLAUDE_ORCHESTRATOR_ACTIVE: "true|false"
+        - CLAUDE_PROMPT_PERSISTENCE_VERSION: "1.0"
+
+        Args:
+            session_state: Session state dict (auto-detected if not provided)
+            auto_detect_compact: Whether to auto-detect post-compact state
+
+        Returns:
+            Dict of environment variables that were set
+
+        Example:
+            >>> sdk = SDK()
+            >>> state = sdk.sessions.get_current_state()
+            >>> env_vars = sdk.sessions.setup_environment_variables(state)
+            >>> print(f"CLAUDE_SESSION_ID: {env_vars['CLAUDE_SESSION_ID']}")
+            >>> print(f"CLAUDE_DELEGATION_ENABLED: {env_vars['CLAUDE_DELEGATION_ENABLED']}")
+        """
+        return self._state_manager.setup_environment_variables(
+            session_state=session_state, auto_detect_compact=auto_detect_compact
+        )
+
+    def record_state(
+        self,
+        session_id: str,
+        source: str,
+        is_post_compact: bool,
+        delegation_enabled: bool,
+        environment_vars: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Store session state metadata for future reference.
+
+        Args:
+            session_id: Current session ID
+            source: Session source ("startup", "resume", "compact", "clear")
+            is_post_compact: Whether this is post-compact
+            delegation_enabled: Whether delegation is enabled
+            environment_vars: Environment variables that were set
+
+        Example:
+            >>> sdk = SDK()
+            >>> sdk.sessions.record_state(
+            ...     session_id="sess-123",
+            ...     source="compact",
+            ...     is_post_compact=True,
+            ...     delegation_enabled=True
+            ... )
+        """
+        self._state_manager.record_state(
+            session_id=session_id,
+            source=source,
+            is_post_compact=is_post_compact,
+            delegation_enabled=delegation_enabled,
+            environment_vars=environment_vars,
+        )
+
+    def detect_compact_automatically(self) -> bool:
+        """
+        Auto-detect if this is post-compact by comparing session IDs.
+
+        Returns:
+            True if this is a post-compact session
+
+        Example:
+            >>> sdk = SDK()
+            >>> if sdk.sessions.detect_compact_automatically():
+            ...     print("This is a post-compact session")
+        """
+        return self._state_manager.detect_compact_automatically()
+
+    def get_state_manager(self) -> SessionStateManager:
+        """
+        Get the underlying SessionStateManager.
+
+        Use this for advanced session state operations.
+
+        Returns:
+            SessionStateManager instance
+
+        Example:
+            >>> sdk = SDK()
+            >>> manager = sdk.sessions.get_state_manager()
+            >>> state = manager.get_current_state()
+        """
+        return self._state_manager

htmlgraph/collections/spike.py

@@ -82,8 +82,14 @@ class SpikeCollection(BaseCollection["SpikeCollection"]):
         all_spikes = self.all()
 
         # Filter by agent if specified
+        # Check both agent_assigned and model_name fields
         if agent:
-            all_spikes = [s for s in all_spikes if s.agent_assigned == agent]
+            all_spikes = [
+                s
+                for s in all_spikes
+                if (s.agent_assigned and agent.lower() in s.agent_assigned.lower())
+                or (s.model_name and agent.lower() in s.model_name.lower())
+            ]
 
         # Normalize to UTC for comparison
         def to_comparable(dt: datetime) -> datetime: