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

htmlgraph/builders/base.py

@@ -1,22 +1,27 @@
+from __future__ import annotations
+
 """
 Base builder class for fluent node creation.
 
 Provides common builder patterns shared across all node types.
 """
 
-from __future__ import annotations
-from typing import TYPE_CHECKING, Any, TypeVar, Generic
+
 from datetime import datetime
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 if TYPE_CHECKING:
-    from htmlgraph.sdk import SDK
     from htmlgraph.models import Node
+    from htmlgraph.sdk import SDK
 
-from htmlgraph.models import Step, Edge
 from htmlgraph.ids import generate_id
+from htmlgraph.models import Edge, Step
 
 # Generic type for the builder subclass
-BuilderT = TypeVar('BuilderT', bound='BaseBuilder')
+BuilderT = TypeVar("BuilderT", bound="BaseBuilder")
+
+# For type hints in helper methods
+from typing_extensions import Self
 
 
 class BaseBuilder(Generic[BuilderT]):
@@ -38,7 +43,7 @@ class BaseBuilder(Generic[BuilderT]):
 
     node_type: str = "node"  # Override in subclasses
 
-    def __init__(self, sdk: 'SDK', title: str, **kwargs):
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
         """
         Initialize builder.
 
@@ -56,9 +61,36 @@ class BaseBuilder(Generic[BuilderT]):
             "steps": [],
             "edges": {},
             "properties": {},
-            **kwargs
+            **kwargs,
         }
 
+    # Helper methods for common patterns
+    def _add_edge(
+        self, edge_type: str, target_id: str, relationship: str | None = None
+    ) -> Self:
+        """Add an edge to the node being built."""
+        if edge_type not in self._data["edges"]:
+            self._data["edges"][edge_type] = []
+        self._data["edges"][edge_type].append(
+            Edge(target_id=target_id, relationship=relationship or edge_type)
+        )
+        return self
+
+    def _set_date(self, field_name: str, date_value: Any) -> Self:
+        """Set a date field in properties, converting to ISO format if needed."""
+        iso_date = (
+            date_value.isoformat() if hasattr(date_value, "isoformat") else date_value
+        )
+        self._data["properties"][field_name] = iso_date
+        return self
+
+    def _append_to_list(self, field_name: str, value: Any) -> Self:
+        """Append a value to a list field in properties, creating list if needed."""
+        if field_name not in self._data["properties"]:
+            self._data["properties"][field_name] = []
+        self._data["properties"][field_name].append(value)
+        return self
+
     def set_priority(self, priority: str) -> BuilderT:
         """Set node priority (low, medium, high, critical)."""
         self._data["priority"] = priority
@@ -87,21 +119,11 @@ class BaseBuilder(Generic[BuilderT]):
 
     def blocks(self, node_id: str) -> BuilderT:
         """Add blocking relationship (this node blocks another)."""
-        if "blocks" not in self._data["edges"]:
-            self._data["edges"]["blocks"] = []
-        self._data["edges"]["blocks"].append(
-            Edge(target_id=node_id, relationship="blocks")
-        )
-        return self  # type: ignore
+        return self._add_edge("blocks", node_id)  # type: ignore
 
     def blocked_by(self, node_id: str) -> BuilderT:
         """Add blocked-by relationship (this node is blocked by another)."""
-        if "blocked_by" not in self._data["edges"]:
-            self._data["edges"]["blocked_by"] = []
-        self._data["edges"]["blocked_by"].append(
-            Edge(target_id=node_id, relationship="blocked_by")
-        )
-        return self  # type: ignore
+        return self._add_edge("blocked_by", node_id)  # type: ignore
 
     def set_track(self, track_id: str) -> BuilderT:
         """Link to a track."""
@@ -131,7 +153,7 @@ class BaseBuilder(Generic[BuilderT]):
         self._data["handoff_timestamp"] = datetime.now()
         return self  # type: ignore
 
-    def save(self) -> 'Node':
+    def save(self) -> Node:
         """
         Save the node and return the Node instance.
 
@@ -140,6 +162,9 @@ class BaseBuilder(Generic[BuilderT]):
 
         Returns:
             Created Node instance
+
+        Raises:
+            ValueError: If node type requires track_id but none is set
         """
         # Generate collision-resistant ID if not provided
         if "id" not in self._data:
@@ -148,28 +173,92 @@ class BaseBuilder(Generic[BuilderT]):
                 title=self._data.get("title", ""),
             )
 
+        # Validate track_id requirement for features
+        node_type = self._data.get("type", self.node_type)
+        if node_type == "feature" and not self._data.get("track_id"):
+            # Get available tracks for helpful error message
+            try:
+                tracks = self._sdk.tracks.all()
+                track_options = "\n".join(
+                    [f"  - {track.id}: {track.title}" for track in tracks[:10]]
+                )
+                if len(tracks) > 10:
+                    track_options += f"\n  ... and {len(tracks) - 10} more tracks"
+
+                error_msg = (
+                    f"Feature '{self._data.get('title', 'Unknown')}' requires a track linkage.\n\n"
+                    f"Use: .set_track('track_id') to link to a track before saving.\n\n"
+                    f"Available tracks:\n{track_options or '  (no tracks found)'}\n\n"
+                    f"Create a track first: sdk.tracks.create('Track Title')"
+                )
+            except Exception:
+                # Fallback error message if we can't fetch tracks
+                error_msg = (
+                    f"Feature '{self._data.get('title', 'Unknown')}' requires a track linkage.\n"
+                    f"Use: .set_track('track_id') to link to a track before saving."
+                )
+
+            raise ValueError(error_msg)
+
         # Import Node here to avoid circular imports
         from htmlgraph.models import Node
-        from htmlgraph.graph import HtmlGraph
 
         node = Node(**self._data)
 
-        # Save to the correct collection directory based on node type
-        # Use the collection's graph, not SDK._graph (which is features-only)
+        # Save to the collection's shared graph (not a new instance)
+        # This ensures the node is visible via collection.get() immediately
         collection_name = self._data.get("type", self.node_type) + "s"
-        graph_path = self._sdk._directory / collection_name
-        graph = HtmlGraph(graph_path, auto_load=False)
-        graph.add(node)
+        collection = getattr(self._sdk, collection_name, None)
+
+        if collection is not None:
+            # Use the collection's shared graph
+            graph = collection._ensure_graph()
+            graph.add(node)
+        else:
+            # Fallback: create new graph (for collections not yet on SDK)
+            from htmlgraph.graph import HtmlGraph
+
+            graph_path = self._sdk._directory / collection_name
+            graph = HtmlGraph(graph_path, auto_load=False)
+            graph.add(node)
+
+        # Log creation event to SQLite for dashboard observability
+        try:
+            action_type = self._data.get("type", self.node_type)
+            self._sdk._log_event(
+                event_type="tool_call",
+                tool_name="SDK.create",
+                input_summary=f"Create {action_type}: {self._data.get('title', 'Untitled')}",
+                output_summary=f"Created {collection_name}/{node.id}",
+                context={
+                    "collection": collection_name,
+                    "node_id": node.id,
+                    "node_type": action_type,
+                    "title": node.title,
+                    "status": self._data.get("status", "todo"),
+                    "priority": self._data.get("priority", "medium"),
+                },
+                cost_tokens=50,
+            )
+        except Exception as e:
+            # Never break save because of logging
+            import logging
+
+            logging.debug(f"Event logging failed: {e}")
 
-        # Log creation event if SessionManager is available and agent is set
-        if hasattr(self._sdk, 'session_manager') and self._sdk.agent:
+        # Also log via SessionManager for backward compatibility
+        if hasattr(self._sdk, "session_manager") and self._sdk.agent:
             try:
                 self._sdk.session_manager._maybe_log_work_item_action(
                     agent=self._sdk.agent,
                     tool="FeatureCreate",
                     summary=f"Created: {collection_name}/{node.id}",
                     feature_id=node.id,
-                    payload={"collection": collection_name, "action": "create", "title": node.title},
+                    payload={
+                        "collection": collection_name,
+                        "action": "create",
+                        "title": node.title,
+                    },
                 )
             except Exception:
                 # Never break save because of logging

htmlgraph/builders/bug.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+"""
+Bug builder for creating bug report nodes.
+
+Extends BaseBuilder with bug-specific methods like
+severity and reproduction steps.
+"""
+
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.builders.base import BaseBuilder
+
+
+class BugBuilder(BaseBuilder["BugBuilder"]):
+    """
+    Fluent builder for creating bugs.
+
+    Inherits common builder methods from BaseBuilder and adds
+    bug-specific methods for issue tracking:
+    - severity: Bug severity level
+    - repro_steps: Steps to reproduce
+    - expected/actual: Expected vs actual behavior
+    - affected_version: Version where bug occurs
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> bug = sdk.bugs.create("Login button unresponsive") \\
+        ...     .set_priority("critical") \\
+        ...     .set_severity("high") \\
+        ...     .set_repro_steps(["Go to login", "Click button", "Nothing happens"]) \\
+        ...     .save()
+    """
+
+    node_type = "bug"
+
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize bug builder with agent attribution."""
+        super().__init__(sdk, title, **kwargs)
+        # Auto-assign agent from SDK for work tracking
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # Log warning if agent not assigned (defensive check)
+            import logging
+
+            logging.warning(
+                f"Creating bug '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
+    def set_severity(self, severity: str) -> BugBuilder:
+        """
+        Set bug severity level.
+
+        Args:
+            severity: Severity level (low, medium, high, critical)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> bug.set_severity("critical")
+        """
+        self._data["severity"] = severity
+        return self
+
+    def set_repro_steps(self, steps: list[str]) -> BugBuilder:
+        """
+        Set steps to reproduce the bug.
+
+        Args:
+            steps: List of reproduction steps
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> bug.set_repro_steps(["Open app", "Click login", "Enter credentials"])
+        """
+        self._data["repro_steps"] = steps
+        return self
+
+    def set_expected_behavior(self, expected: str) -> BugBuilder:
+        """
+        Set expected behavior.
+
+        Args:
+            expected: What should happen
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> bug.set_expected_behavior("User should be logged in")
+        """
+        self._data["expected_behavior"] = expected
+        return self
+
+    def set_actual_behavior(self, actual: str) -> BugBuilder:
+        """
+        Set actual (buggy) behavior.
+
+        Args:
+            actual: What actually happens
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> bug.set_actual_behavior("Button does nothing")
+        """
+        self._data["actual_behavior"] = actual
+        return self
+
+    def set_affected_version(self, version: str) -> BugBuilder:
+        """
+        Set the affected version.
+
+        Args:
+            version: Version string where bug occurs
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> bug.set_affected_version("1.2.3")
+        """
+        self._data["affected_version"] = version
+        return self
+
+    def set_environment(self, environment: str) -> BugBuilder:
+        """
+        Set the environment where bug occurs.
+
+        Args:
+            environment: Environment description (e.g., "Chrome 120, macOS")
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> bug.set_environment("Chrome 120, macOS Sonoma")
+        """
+        self._data["environment"] = environment
+        return self

htmlgraph/builders/chore.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+"""
+Chore builder for creating maintenance task nodes.
+
+Extends BaseBuilder with chore-specific methods like
+chore type and recurrence.
+"""
+
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.builders.base import BaseBuilder
+
+
+class ChoreBuilder(BaseBuilder["ChoreBuilder"]):
+    """
+    Fluent builder for creating chores.
+
+    Inherits common builder methods from BaseBuilder and adds
+    chore-specific methods for maintenance work:
+    - chore_type: Classification of chore
+    - is_recurring: Whether this repeats
+    - recurrence_interval: How often it recurs
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> chore = sdk.chores.create("Update dependencies") \\
+        ...     .set_priority("low") \\
+        ...     .set_chore_type("maintenance") \\
+        ...     .set_recurring(interval_days=30) \\
+        ...     .save()
+    """
+
+    node_type = "chore"
+
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize chore builder with agent attribution."""
+        super().__init__(sdk, title, **kwargs)
+        # Auto-assign agent from SDK for work tracking
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # Log warning if agent not assigned (defensive check)
+            import logging
+
+            logging.warning(
+                f"Creating chore '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
+    def set_chore_type(self, chore_type: str) -> ChoreBuilder:
+        """
+        Set the type of chore.
+
+        Args:
+            chore_type: Type (maintenance, refactor, cleanup, upgrade, documentation)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> chore.set_chore_type("maintenance")
+        """
+        self._data["chore_type"] = chore_type
+        return self
+
+    def set_recurring(self, interval_days: int | None = None) -> ChoreBuilder:
+        """
+        Mark chore as recurring with optional interval.
+
+        Args:
+            interval_days: Days between occurrences (optional)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> chore.set_recurring(interval_days=7)  # Weekly
+        """
+        self._data["is_recurring"] = True
+        if interval_days:
+            self._data["recurrence_interval_days"] = interval_days
+        return self
+
+    def set_scope(self, scope: str) -> ChoreBuilder:
+        """
+        Set the scope of the chore.
+
+        Args:
+            scope: Scope description (e.g., "entire codebase", "auth module")
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> chore.set_scope("authentication module")
+        """
+        self._data["scope"] = scope
+        return self
+
+    def set_estimated_effort(self, hours: float) -> ChoreBuilder:
+        """
+        Set estimated effort in hours.
+
+        Args:
+            hours: Estimated hours to complete
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> chore.set_estimated_effort(2.5)
+        """
+        self._data["estimated_effort_hours"] = hours
+        return self

htmlgraph/builders/epic.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+"""
+Epic builder for creating large body of work nodes.
+
+Extends BaseBuilder with epic-specific methods like
+child features and milestones.
+"""
+
+
+from datetime import date
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.builders.base import BaseBuilder
+
+
+class EpicBuilder(BaseBuilder["EpicBuilder"]):
+    """
+    Fluent builder for creating epics.
+
+    Inherits common builder methods from BaseBuilder and adds
+    epic-specific methods for large initiatives:
+    - child_features: Features contained in this epic
+    - target_date: Target completion date
+    - success_criteria: How success is measured
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> epic = sdk.epics.create("v2.0 Release") \\
+        ...     .set_priority("high") \\
+        ...     .set_target_date(date(2025, 3, 1)) \\
+        ...     .add_child_feature("feat-001") \\
+        ...     .add_child_feature("feat-002") \\
+        ...     .save()
+    """
+
+    node_type = "epic"
+
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize epic builder with agent attribution."""
+        super().__init__(sdk, title, **kwargs)
+        # Auto-assign agent from SDK for work tracking
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # Log warning if agent not assigned (defensive check)
+            import logging
+
+            logging.warning(
+                f"Creating epic '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
+    def add_child_feature(self, feature_id: str) -> EpicBuilder:
+        """
+        Add a feature as a child of this epic.
+
+        Args:
+            feature_id: ID of the child feature
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> epic.add_child_feature("feat-abc123")
+        """
+        return self._add_edge("contains", feature_id)
+
+    def add_child_features(self, feature_ids: list[str]) -> EpicBuilder:
+        """
+        Add multiple features as children of this epic.
+
+        Args:
+            feature_ids: List of child feature IDs
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> epic.add_child_features(["feat-001", "feat-002", "feat-003"])
+        """
+        for fid in feature_ids:
+            self.add_child_feature(fid)
+        return self
+
+    def set_target_date(self, target: date) -> EpicBuilder:
+        """
+        Set target completion date.
+
+        Args:
+            target: Target date for epic completion
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> epic.set_target_date(date(2025, 6, 1))
+        """
+        return self._set_date("target_date", target)
+
+    def set_success_criteria(self, criteria: list[str]) -> EpicBuilder:
+        """
+        Set success criteria for the epic.
+
+        Args:
+            criteria: List of success criteria
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> epic.set_success_criteria(["100% test coverage", "Zero critical bugs"])
+        """
+        self._data["success_criteria"] = criteria
+        return self
+
+    def set_business_value(self, value: str) -> EpicBuilder:
+        """
+        Set the business value statement.
+
+        Args:
+            value: Business value description
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> epic.set_business_value("Increase user retention by 20%")
+        """
+        self._data["business_value"] = value
+        return self
+
+    def set_stakeholder(self, stakeholder: str) -> EpicBuilder:
+        """
+        Set the primary stakeholder.
+
+        Args:
+            stakeholder: Stakeholder name or role
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> epic.set_stakeholder("Product Team")
+        """
+        self._data["stakeholder"] = stakeholder
+        return self