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

htmlgraph/builders/phase.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+"""
+Phase builder for creating project phase nodes.
+
+Extends BaseBuilder with phase-specific methods like
+phase ordering and dependencies.
+"""
+
+
+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 PhaseBuilder(BaseBuilder["PhaseBuilder"]):
+    """
+    Fluent builder for creating phases.
+
+    Inherits common builder methods from BaseBuilder and adds
+    phase-specific methods for project planning:
+    - phase_number: Ordering within project
+    - start_date/end_date: Phase timeline
+    - deliverables: What the phase produces
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> phase = sdk.phases.create("Phase 1: Core Library") \\
+        ...     .set_priority("high") \\
+        ...     .set_phase_number(1) \\
+        ...     .set_deliverables(["Core API", "Unit tests", "Documentation"]) \\
+        ...     .save()
+    """
+
+    node_type = "phase"
+
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize phase 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 phase '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
+    def set_phase_number(self, number: int) -> PhaseBuilder:
+        """
+        Set the phase number for ordering.
+
+        Args:
+            number: Phase sequence number
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> phase.set_phase_number(1)
+        """
+        self._data["phase_number"] = number
+        return self
+
+    def set_start_date(self, start: date) -> PhaseBuilder:
+        """
+        Set phase start date.
+
+        Args:
+            start: Start date
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> phase.set_start_date(date(2025, 1, 1))
+        """
+        return self._set_date("start_date", start)
+
+    def set_end_date(self, end: date) -> PhaseBuilder:
+        """
+        Set phase end date.
+
+        Args:
+            end: End date
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> phase.set_end_date(date(2025, 3, 31))
+        """
+        return self._set_date("end_date", end)
+
+    def set_deliverables(self, deliverables: list[str]) -> PhaseBuilder:
+        """
+        Set phase deliverables.
+
+        Args:
+            deliverables: List of deliverable items
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> phase.set_deliverables(["API docs", "SDK release", "Examples"])
+        """
+        self._data["deliverables"] = deliverables
+        return self
+
+    def add_milestone(self, milestone: str) -> PhaseBuilder:
+        """
+        Add a milestone to the phase.
+
+        Args:
+            milestone: Milestone description
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> phase.add_milestone("Alpha release")
+        """
+        return self._append_to_list("milestones", milestone)
+
+    def follows(self, phase_id: str) -> PhaseBuilder:
+        """
+        Set this phase to follow another phase.
+
+        Args:
+            phase_id: ID of the preceding phase
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> phase.follows("phase-core-library")
+        """
+        return self._add_edge("follows", phase_id)
+
+    def set_exit_criteria(self, criteria: list[str]) -> PhaseBuilder:
+        """
+        Set exit criteria for completing the phase.
+
+        Args:
+            criteria: List of exit criteria
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> phase.set_exit_criteria(["All tests passing", "Code review complete"])
+        """
+        self._data["exit_criteria"] = criteria
+        return self

htmlgraph/builders/spike.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Spike builder for creating spike investigation nodes.
 
@@ -5,19 +7,19 @@ Extends BaseBuilder with spike-specific methods like
 spike_type and timebox_hours.
 """
 
-from __future__ import annotations
-from typing import TYPE_CHECKING
+
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from htmlgraph.sdk import SDK
     from htmlgraph.models import Node
+    from htmlgraph.sdk import SDK
 
 from htmlgraph.builders.base import BaseBuilder
-from htmlgraph.models import SpikeType, Spike
 from htmlgraph.ids import generate_id
+from htmlgraph.models import Spike, SpikeType
 
 
-class SpikeBuilder(BaseBuilder['SpikeBuilder']):
+class SpikeBuilder(BaseBuilder["SpikeBuilder"]):
     """
     Fluent builder for creating spikes.
 
@@ -39,7 +41,7 @@ class SpikeBuilder(BaseBuilder['SpikeBuilder']):
 
     node_type = "spike"
 
-    def __init__(self, sdk: 'SDK', title: str, **kwargs):
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
         """Initialize spike builder with spike-specific defaults."""
         super().__init__(sdk, title, **kwargs)
         # Set spike-specific defaults
@@ -47,8 +49,20 @@ class SpikeBuilder(BaseBuilder['SpikeBuilder']):
             self._data["spike_type"] = SpikeType.GENERAL
         if "timebox_hours" not in self._data:
             self._data["timebox_hours"] = 4
+        # Auto-assign agent from SDK (critical for work tracking)
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # This should never happen now because SDK enforces agent parameter,
+            # but log warning if it does occur (for debugging)
+            import logging
+
+            logging.warning(
+                f"Creating spike '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "This will make work tracking impossible. Pass agent='name' to SDK() initialization."
+            )
 
-    def set_spike_type(self, spike_type: SpikeType) -> 'SpikeBuilder':
+    def set_spike_type(self, spike_type: SpikeType) -> SpikeBuilder:
         """
         Set the spike investigation type.
 
@@ -64,7 +78,7 @@ class SpikeBuilder(BaseBuilder['SpikeBuilder']):
         self._data["spike_type"] = spike_type
         return self
 
-    def set_timebox_hours(self, hours: float) -> 'SpikeBuilder':
+    def set_timebox_hours(self, hours: float) -> SpikeBuilder:
         """
         Set the time budget for this spike.
 
@@ -80,23 +94,36 @@ class SpikeBuilder(BaseBuilder['SpikeBuilder']):
         self._data["timebox_hours"] = int(hours)
         return self
 
-    def set_findings(self, findings: str) -> 'SpikeBuilder':
+    def set_findings(self, findings: str) -> SpikeBuilder:
         """
         Set the findings/learnings from spike investigation.
 
         Args:
-            findings: Summary of what was learned
+            findings: Summary of what was learned (must be non-empty, min 10 chars)
 
         Returns:
             Self for method chaining
 
+        Raises:
+            ValueError: If findings are empty or too short
+
         Example:
             >>> spike.set_findings("OAuth2 is best fit. Recommend Auth0.")
         """
-        self._data["findings"] = findings
+        # Validate findings quality
+        stripped = findings.strip() if findings else ""
+        if not stripped:
+            raise ValueError(
+                "Findings cannot be empty. Provide meaningful investigation results."
+            )
+        if len(stripped) < 10:
+            raise ValueError(
+                "Findings must be at least 10 characters. Provide detailed results."
+            )
+        self._data["findings"] = stripped
         return self
 
-    def set_decision(self, decision: str) -> 'SpikeBuilder':
+    def set_decision(self, decision: str) -> SpikeBuilder:
         """
         Set the final decision made based on spike results.
 
@@ -112,7 +139,7 @@ class SpikeBuilder(BaseBuilder['SpikeBuilder']):
         self._data["decision"] = decision
         return self
 
-    def save(self) -> 'Node':
+    def save(self) -> Node:
         """
         Save the spike and return the Spike instance.
 
@@ -129,13 +156,19 @@ class SpikeBuilder(BaseBuilder['SpikeBuilder']):
                 title=self._data.get("title", ""),
             )
 
-        from htmlgraph.graph import HtmlGraph
-
         spike = Spike(**self._data)
 
-        # Save to spikes directory, not features directory
-        graph_path = self._sdk._directory / "spikes"
-        graph = HtmlGraph(graph_path, auto_load=False)
-        graph.add(spike)
+        # Save to the collection's shared graph
+        # This ensures the spike is visible via sdk.spikes.get() immediately
+        if hasattr(self._sdk, "spikes") and self._sdk.spikes is not None:
+            graph = self._sdk.spikes._ensure_graph()
+            graph.add(spike)
+        else:
+            # Fallback: create new graph
+            from htmlgraph.graph import HtmlGraph
+
+            graph_path = self._sdk._directory / "spikes"
+            graph = HtmlGraph(graph_path, auto_load=False)
+            graph.add(spike)
 
         return spike