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

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

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Base collection class for managing nodes.
 
@@ -5,7 +11,6 @@ Provides common collection functionality for all node types
 with lazy-loading, filtering, and batch operations.
 """
 
-from __future__ import annotations
 
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager
@@ -69,9 +74,22 @@ class BaseCollection(Generic[CollectionT]):
         self._collection_name = collection_name or self._collection_name
         self._node_type = node_type or self._node_type
         self._graph: HtmlGraph | None = None  # Lazy-loaded
+        self._ref_manager: Any = None  # Set by SDK during initialization
 
     def _ensure_graph(self) -> HtmlGraph:
-        """Get the graph for this collection, using SDK's shared instances where available."""
+        """
+        Get or initialize the graph for this collection.
+
+        Uses SDK's shared graph instances where available to avoid creating
+        multiple graph objects for the same collection. Creates a new instance
+        for unrecognized collections.
+
+        Returns:
+            HtmlGraph instance for this collection
+
+        Note:
+            This method is lazy - the graph is only loaded on first access.
+        """
         if self._graph is None:
             # Use SDK's shared graph instances to avoid multiple graph objects
             if self._collection_name == "features" and hasattr(self._sdk, "_graph"):
@@ -91,8 +109,72 @@ class BaseCollection(Generic[CollectionT]):
 
         return self._graph
 
+    def __getattribute__(self, name: str) -> Any:
+        """
+        Override attribute access to provide helpful error messages.
+
+        When an attribute doesn't exist, provides suggestions for common
+        mistakes and similar method names to improve discoverability.
+
+        Args:
+            name: Attribute name being accessed
+
+        Returns:
+            The requested attribute
+
+        Raises:
+            AttributeError: With helpful suggestions if attribute not found
+        """
+        try:
+            return object.__getattribute__(self, name)
+        except AttributeError as e:
+            # Get available methods
+            available = [m for m in dir(self) if not m.startswith("_")]
+
+            # Common mistakes mapping
+            common_mistakes = {
+                "mark_complete": "mark_done",
+                "complete": "Use complete(node_id) for single item or mark_done([ids]) for batch",
+                "finish": "mark_done",
+                "end": "mark_done",
+                "update_status": "edit() context manager or batch_update()",
+                "mark_as_done": "mark_done",
+                "set_done": "mark_done",
+                "complete_all": "mark_done",
+            }
+
+            suggestions = []
+            if name in common_mistakes:
+                suggestions.append(f"Did you mean: {common_mistakes[name]}")
+
+            # Find similar method names
+            similar = [
+                m
+                for m in available
+                if name.lower() in m.lower() or m.lower() in name.lower()
+            ]
+            if similar:
+                suggestions.append(f"Similar methods: {', '.join(similar[:5])}")
+
+            # Build helpful error message
+            error_msg = f"'{type(self).__name__}' has no attribute '{name}'."
+            if suggestions:
+                error_msg += "\n\n" + "\n".join(suggestions)
+            error_msg += f"\n\nAvailable methods: {', '.join(available[:15])}"
+            error_msg += "\n\nTip: Use sdk.help() to see all available operations."
+
+            raise AttributeError(error_msg) from e
+
     def __dir__(self) -> list[str]:
-        """Return attributes with most useful ones first for discoverability."""
+        """
+        Return attributes with most useful ones first.
+
+        Orders attributes to show commonly-used methods first in auto-complete
+        and help() output, improving discoverability for new users.
+
+        Returns:
+            List of attribute names, ordered by priority then alphabetically
+        """
         priority = [
             # Creation and retrieval
             "create",
@@ -124,6 +206,39 @@ class BaseCollection(Generic[CollectionT]):
         # Return priority items first, then regular, then dunder
         return priority + regular + dunder
 
+    def set_ref_manager(self, ref_manager: Any) -> None:
+        """
+        Set the ref manager for this collection.
+
+        Called by SDK during initialization to enable short ref support.
+
+        Args:
+            ref_manager: RefManager instance from SDK
+        """
+        self._ref_manager = ref_manager
+
+    def get_ref(self, node_id: str) -> str | None:
+        """
+        Get short ref for a node in this collection.
+
+        Convenience method to get ref without accessing SDK directly.
+
+        Args:
+            node_id: Full node ID like "feat-a1b2c3d4"
+
+        Returns:
+            Short ref like "@f1", or None if ref manager not available
+
+        Example:
+            >>> feature = sdk.features.get("feat-abc123")
+            >>> ref = sdk.features.get_ref(feature.id)
+            >>> logger.info("%s", ref)  # "@f1"
+        """
+        if self._ref_manager:
+            result = self._ref_manager.get_ref(node_id)
+            return cast(str | None, result)
+        return None
+
     def create(
         self, title: str, priority: str = "medium", status: str = "todo", **kwargs: Any
     ) -> Any:
@@ -356,7 +471,7 @@ class BaseCollection(Generic[CollectionT]):
 
         Example:
             >>> count = sdk.features.batch_delete(["feat-001", "feat-002", "feat-003"])
-            >>> print(f"Deleted {count} features")
+            >>> logger.info(f"Deleted {count} features")
         """
         graph = self._ensure_graph()
         return cast(int, graph.batch_delete(node_ids))
@@ -418,7 +533,7 @@ class BaseCollection(Generic[CollectionT]):
 
         return count
 
-    def mark_done(self, node_ids: list[str]) -> int:
+    def mark_done(self, node_ids: list[str]) -> dict[str, Any]:
         """
         Batch mark nodes as done.
 
@@ -426,12 +541,55 @@ class BaseCollection(Generic[CollectionT]):
             node_ids: List of node IDs to mark as done
 
         Returns:
-            Number of nodes updated
+            Dict with 'success_count', 'failed_ids', and 'warnings'
 
         Example:
-            >>> sdk.features.mark_done(["feat-001", "feat-002"])
+            >>> result = sdk.features.mark_done(["feat-001", "feat-002"])
+            >>> logger.info(f"Completed {result['success_count']} of {len(node_ids)}")
+            >>> if result['failed_ids']:
+            ...     logger.info(f"Failed: {result['failed_ids']}")
         """
-        return self.batch_update(node_ids, {"status": "done"})
+        graph = self._ensure_graph()
+        results: dict[str, Any] = {"success_count": 0, "failed_ids": [], "warnings": []}
+
+        for node_id in node_ids:
+            try:
+                node = graph.get(node_id)
+                if not node:
+                    results["failed_ids"].append(node_id)
+                    results["warnings"].append(f"Node {node_id} not found")
+                    continue
+
+                node.status = "done"
+                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)}")
+
+        return results
 
     def assign(self, node_ids: list[str], agent: str) -> int:
         """
@@ -454,13 +612,15 @@ class BaseCollection(Generic[CollectionT]):
         """
         Start working on a node (feature/bug/etc).
 
-        Delegates to SessionManager to:
+        Delegates to SessionManager if available for smart tracking:
         1. Check WIP limits
         2. Ensure not claimed by others
         3. Auto-claim for agent
         4. Link to active session
         5. Log 'FeatureStart' event
 
+        Falls back to simple status update if SessionManager not available.
+
         Args:
             node_id: Node ID to start
             agent: Agent ID (defaults to SDK agent)
@@ -470,6 +630,10 @@ class BaseCollection(Generic[CollectionT]):
 
         Raises:
             NodeNotFoundError: If node not found
+
+        Example:
+            >>> sdk.features.start('feat-abc123')
+            >>> sdk.features.start('feat-xyz', agent='claude')
         """
         agent = agent or self._sdk.agent
 
@@ -502,14 +666,17 @@ class BaseCollection(Generic[CollectionT]):
         transcript_id: str | None = None,
     ) -> Node | None:
         """
-        Complete a node.
+        Mark a node as complete.
 
-        Delegates to SessionManager to:
-        1. Update status
+        Delegates to SessionManager if available for event logging and
+        transcript linking:
+        1. Update status to 'done'
         2. Log 'FeatureComplete' event
         3. Release claim (optional behavior)
         4. Link transcript if provided (for parallel agent tracking)
 
+        Falls back to simple status update if SessionManager not available.
+
         Args:
             node_id: Node ID to complete
             agent: Agent ID (defaults to SDK agent)
@@ -521,6 +688,10 @@ class BaseCollection(Generic[CollectionT]):
 
         Raises:
             NodeNotFoundError: If node not found
+
+        Example:
+            >>> sdk.features.complete('feat-abc123')
+            >>> sdk.features.complete('feat-xyz', agent='claude', transcript_id='trans-123')
         """
         agent = agent or self._sdk.agent
 
@@ -551,11 +722,13 @@ class BaseCollection(Generic[CollectionT]):
         """
         Claim a node for an agent.
 
-        Delegates to SessionManager to:
+        Delegates to SessionManager if available for ownership tracking:
         1. Check ownership rules
         2. Update assignment
         3. Log 'FeatureClaim' event
 
+        Falls back to simple assignment if SessionManager not available.
+
         Args:
             node_id: Node ID to claim
             agent: Agent ID (defaults to SDK agent)
@@ -567,6 +740,10 @@ class BaseCollection(Generic[CollectionT]):
             ValueError: If agent not provided and SDK has no agent
             NodeNotFoundError: If node not found
             ClaimConflictError: If node already claimed by different agent
+
+        Example:
+            >>> sdk.features.claim('feat-abc123')
+            >>> sdk.features.claim('feat-xyz', agent='claude')
         """
         agent = agent or self._sdk.agent
         if not agent:
@@ -601,11 +778,13 @@ class BaseCollection(Generic[CollectionT]):
         """
         Release a claimed node.
 
-        Delegates to SessionManager to:
+        Delegates to SessionManager if available for ownership tracking:
         1. Verify ownership
         2. Clear assignment
         3. Log 'FeatureRelease' event
 
+        Falls back to simple assignment clearing if SessionManager not available.
+
         Args:
             node_id: Node ID to release
             agent: Agent ID (defaults to SDK agent)
@@ -615,6 +794,10 @@ class BaseCollection(Generic[CollectionT]):
 
         Raises:
             NodeNotFoundError: If node not found
+
+        Example:
+            >>> sdk.features.release('feat-abc123')
+            >>> sdk.features.release('feat-xyz', agent='claude')
         """
         # SessionManager.release_feature requires an agent to verify ownership
         agent = agent or self._sdk.agent

htmlgraph/collections/bug.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Bug collection for managing bug report work items.
 
 Extends BaseCollection with bug-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/chore.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Chore collection for managing maintenance task work items.
 
 Extends BaseCollection with chore-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/epic.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Epic collection for managing large body of work items.
 
 Extends BaseCollection with epic-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/feature.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Feature collection for managing feature work items.
 
 Extends BaseCollection with feature-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/insight.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 SessionInsight collection for managing session insights.
 
 Extends BaseCollection with insight-specific query methods.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/metric.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 AggregatedMetric collection for managing aggregated metrics.
 
 Extends BaseCollection with metric-specific query methods.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/pattern.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Pattern collection for managing workflow patterns.
 
 Extends BaseCollection with pattern-specific query methods.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/phase.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Phase collection for managing project phase work items.
 
 Extends BaseCollection with phase-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING