htmlgraph 0.2.2__tar.gz → 0.3.0__tar.gz

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.2.2
+Version: 0.3.0
 Summary: HTML is All You Need - Graph database on web standards
 Project-URL: Homepage, https://github.com/Shakes-tzd/htmlgraph
 Project-URL: Documentation, https://github.com/Shakes-tzd/htmlgraph#readme

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "htmlgraph"
-version = "0.2.2"
+version = "0.3.0"
 description = "HTML is All You Need - Graph database on web standards"
 authors = [{name = "Shakes", email = "shakestzd@gmail.com"}]
 readme = "README.md"

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/src/python/htmlgraph/__init__.py

@@ -12,7 +12,7 @@ from htmlgraph.server import serve
 from htmlgraph.session_manager import SessionManager
 from htmlgraph.sdk import SDK
 
-__version__ = "0.1.3"
+__version__ = "0.3.0"
 __all__ = [
     "Node",
     "Edge",

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/src/python/htmlgraph/converter.py

@@ -253,14 +253,24 @@ class NodeConverter:
             return html_to_node(filepath)
         return None
 
-    def load_all(self, pattern: str = "*.html") -> list[Node]:
-        """Load all nodes matching pattern."""
+    def load_all(self, pattern: str | list[str] = "*.html") -> list[Node]:
+        """
+        Load all nodes matching pattern(s).
+
+        Args:
+            pattern: Glob pattern(s) to match. Can be a single pattern or list of patterns.
+                     Examples: "*.html", ["*.html", "*/index.html"]
+        """
         nodes = []
-        for filepath in self.directory.glob(pattern):
-            try:
-                nodes.append(html_to_node(filepath))
-            except (ValueError, KeyError):
-                continue  # Skip malformed files
+        patterns = [pattern] if isinstance(pattern, str) else pattern
+
+        for pat in patterns:
+            for filepath in self.directory.glob(pat):
+                if filepath.is_file():  # Skip directories
+                    try:
+                        nodes.append(html_to_node(filepath))
+                    except (ValueError, KeyError):
+                        continue  # Skip malformed files
         return nodes
 
     def save(self, node: Node) -> Path:

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/src/python/htmlgraph/file_watcher.py

@@ -99,7 +99,9 @@ class GraphWatcher:
             self.handlers[collection] = handler
 
             # Watch the collection directory
-            self.observer.schedule(handler, str(collection_dir), recursive=False)
+            # Use recursive=True for tracks since they're stored in subdirectories
+            recursive = (collection == "tracks")
+            self.observer.schedule(handler, str(collection_dir), recursive=recursive)
 
         self.observer.start()
         print(f"[FileWatcher] Watching {self.graph_dir} for changes...")

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/src/python/htmlgraph/graph.py

@@ -36,7 +36,7 @@ class HtmlGraph:
         directory: Path | str,
         stylesheet_path: str = "../styles.css",
         auto_load: bool = True,
-        pattern: str = "*.html"
+        pattern: str | list[str] = "*.html"
     ):
         """
         Initialize graph from a directory.
@@ -45,7 +45,8 @@ class HtmlGraph:
             directory: Directory containing HTML node files
             stylesheet_path: Default stylesheet path for new files
             auto_load: Whether to load all nodes on init
-            pattern: Glob pattern for node files
+            pattern: Glob pattern(s) for node files. Can be a single pattern or list.
+                     Examples: "*.html", ["*.html", "*/index.html"]
         """
         self.directory = Path(directory)
         self.directory.mkdir(parents=True, exist_ok=True)
@@ -195,16 +196,19 @@ class HtmlGraph:
         """
         matching = []
 
-        for filepath in self.directory.glob(self.pattern):
-            try:
-                parser = HtmlParser.from_file(filepath)
-                # Query for article matching selector
-                if parser.query(f"article{selector}"):
-                    node_id = parser.get_node_id()
-                    if node_id and node_id in self._nodes:
-                        matching.append(self._nodes[node_id])
-            except Exception:
-                continue
+        patterns = [self.pattern] if isinstance(self.pattern, str) else self.pattern
+        for pat in patterns:
+            for filepath in self.directory.glob(pat):
+                if filepath.is_file():
+                    try:
+                        parser = HtmlParser.from_file(filepath)
+                        # Query for article matching selector
+                        if parser.query(f"article{selector}"):
+                            node_id = parser.get_node_id()
+                            if node_id and node_id in self._nodes:
+                                matching.append(self._nodes[node_id])
+                    except Exception:
+                        continue
 
         return matching
 

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/src/python/htmlgraph/models.py

@@ -235,6 +235,9 @@ class Node(BaseModel):
         # Agent attribute
         agent_attr = f' data-agent-assigned="{self.agent_assigned}"' if self.agent_assigned else ""
 
+        # Track ID attribute
+        track_attr = f' data-track-id="{self.track_id}"' if self.track_id else ""
+
         return f'''<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -250,7 +253,7 @@ class Node(BaseModel):
              data-status="{self.status}"
              data-priority="{self.priority}"
              data-created="{self.created.isoformat()}"
-             data-updated="{self.updated.isoformat()}"{agent_attr}>
+             data-updated="{self.updated.isoformat()}"{agent_attr}{track_attr}>
 
         <header>
             <h1>{self.title}</h1>

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/src/python/htmlgraph/sdk.py

@@ -47,6 +47,7 @@ from dataclasses import dataclass
 from htmlgraph.models import Node, Step, Edge
 from htmlgraph.graph import HtmlGraph
 from htmlgraph.agents import AgentInterface
+from htmlgraph.track_builder import TrackCollection
 
 
 @dataclass
@@ -409,7 +410,7 @@ class SDK:
 
         # Non-work collections
         self.sessions = Collection(self, "sessions", "session")
-        self.tracks = Collection(self, "tracks", "track")
+        self.tracks = TrackCollection(self)  # Use specialized collection with builder support
         self.agents = Collection(self, "agents", "agent")
 
     @staticmethod

{htmlgraph-0.2.2 → htmlgraph-0.3.0}/src/python/htmlgraph/server.py

@@ -54,65 +54,62 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
             # Tracks support both file-based (track-xxx.html) and directory-based (track-xxx/index.html)
             if collection == "tracks":
                 from htmlgraph.planning import Track
+                from htmlgraph.converter import html_to_node
 
                 graph = HtmlGraph(
                     collection_dir,
                     stylesheet_path="../styles.css",
-                    auto_load=False  # Manual load to handle both patterns
+                    auto_load=False,  # Manual load to convert to Track objects
+                    pattern=["*.html", "*/index.html"]
                 )
 
-                # Helper function to convert Node to Track with file existence checks
+                # Helper to convert Node to Track with has_spec/has_plan detection
                 def node_to_track(node: Node, filepath: Path) -> Track:
-                    """Convert a Node to a Track with has_spec/has_plan detection."""
-                    # Determine track directory
-                    if filepath.name == "index.html":
-                        # Directory-based: track-id/index.html
-                        track_dir = filepath.parent
-                    else:
-                        # File-based: track-id.html (no spec/plan support)
-                        track_dir = None
-
-                    # Check for spec and plan files
-                    has_spec = track_dir and (track_dir / "spec.html").exists() if track_dir else False
-                    has_plan = track_dir and (track_dir / "plan.html").exists() if track_dir else False
-
-                    # Create Track object from Node data
-                    track_data = {
-                        "id": node.id,
-                        "title": node.title,
-                        "description": node.content or "",
-                        "status": node.status if node.status in ["planned", "active", "completed", "abandoned"] else "planned",
-                        "priority": node.priority,
-                        "created": node.created,
-                        "updated": node.updated,
-                        "has_spec": has_spec,
-                        "has_plan": has_plan,
-                        "features": [],  # Will be populated from properties if present
-                        "sessions": [],  # Will be populated from properties if present
-                    }
-
-                    return Track(**track_data)
-
-                # Load file-based tracks (track-xxx.html)
-                for filepath in collection_dir.glob("*.html"):
-                    try:
-                        from htmlgraph.converter import html_to_node
-                        node = html_to_node(filepath)
-                        track = node_to_track(node, filepath)
-                        graph._nodes[track.id] = track
-                    except Exception:
-                        continue
-
-                # Load directory-based tracks (track-xxx/index.html)
-                for filepath in collection_dir.glob("*/index.html"):
-                    try:
-                        from htmlgraph.converter import html_to_node
-                        node = html_to_node(filepath)
-                        track = node_to_track(node, filepath)
-                        graph._nodes[track.id] = track
-                    except Exception:
-                        continue
+                    track_dir = filepath.parent if filepath.name == "index.html" else None
+                    has_spec = (track_dir / "spec.html").exists() if track_dir else False
+                    has_plan = (track_dir / "plan.html").exists() if track_dir else False
+
+                    return Track(
+                        id=node.id,
+                        title=node.title,
+                        description=node.content or "",
+                        status=node.status if node.status in ["planned", "active", "completed", "abandoned"] else "planned",
+                        priority=node.priority,
+                        created=node.created,
+                        updated=node.updated,
+                        has_spec=has_spec,
+                        has_plan=has_plan,
+                        features=[],
+                        sessions=[]
+                    )
 
+                # Load and convert tracks
+                patterns = graph.pattern if isinstance(graph.pattern, list) else [graph.pattern]
+                for pat in patterns:
+                    for filepath in collection_dir.glob(pat):
+                        if filepath.is_file():
+                            try:
+                                node = html_to_node(filepath)
+                                track = node_to_track(node, filepath)
+                                graph._nodes[track.id] = track
+                            except Exception:
+                                continue
+
+                # Override reload to maintain Track conversion
+                def reload_tracks():
+                    graph._nodes.clear()
+                    for pat in patterns:
+                        for filepath in collection_dir.glob(pat):
+                            if filepath.is_file():
+                                try:
+                                    node = html_to_node(filepath)
+                                    track = node_to_track(node, filepath)
+                                    graph._nodes[track.id] = track
+                                except Exception:
+                                    continue
+                    return len(graph._nodes)
+
+                graph.reload = reload_tracks
                 self.graphs[collection] = graph
             else:
                 self.graphs[collection] = HtmlGraph(

htmlgraph-0.3.0/src/python/htmlgraph/track_builder.py

@@ -0,0 +1,261 @@
+"""
+Track Builder for agent-friendly track creation.
+"""
+from __future__ import annotations
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+import re
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.planning import Track, Spec, Plan, Phase, Task, Requirement, AcceptanceCriterion
+
+
+class TrackBuilder:
+    """
+    Fluent builder for creating tracks with spec and plan.
+
+    Example:
+        track = sdk.tracks.builder() \\
+            .title("Multi-Agent Collaboration") \\
+            .description("Enable seamless agent collaboration") \\
+            .priority("high") \\
+            .with_spec(
+                overview="Agents can work together...",
+                requirements=[
+                    ("Add assigned_agent field", "must-have"),
+                    ("Implement claim CLI", "must-have")
+                ]
+            ) \\
+            .with_plan_phases([
+                ("Phase 1", ["Add field (1h)", "Implement CLI (2h)"]),
+                ("Phase 2", ["Add notes (1h)", "Update hooks (2h)"])
+            ]) \\
+            .create()
+    """
+
+    def __init__(self, sdk: SDK):
+        self.sdk = sdk
+        self._title = None
+        self._description = ""
+        self._priority = "medium"
+        self._spec_data = {}
+        self._plan_phases = []
+
+    def title(self, title: str) -> 'TrackBuilder':
+        """Set track title."""
+        self._title = title
+        return self
+
+    def description(self, desc: str) -> 'TrackBuilder':
+        """Set track description."""
+        self._description = desc
+        return self
+
+    def priority(self, priority: str) -> 'TrackBuilder':
+        """Set track priority (low/medium/high/critical)."""
+        self._priority = priority
+        return self
+
+    def with_spec(
+        self,
+        overview: str = "",
+        context: str = "",
+        requirements: list = None,
+        acceptance_criteria: list = None
+    ) -> 'TrackBuilder':
+        """
+        Add spec content to track.
+
+        Args:
+            overview: High-level summary
+            context: Background and current state
+            requirements: List of (description, priority) tuples or strings
+            acceptance_criteria: List of strings or (description, test_case) tuples
+        """
+        self._spec_data = {
+            "overview": overview,
+            "context": context,
+            "requirements": requirements or [],
+            "acceptance_criteria": acceptance_criteria or []
+        }
+        return self
+
+    def with_plan_phases(self, phases: list[tuple[str, list[str]]]) -> 'TrackBuilder':
+        """
+        Add plan phases with tasks.
+
+        Args:
+            phases: List of (phase_name, [task_descriptions]) tuples
+                    Task descriptions can include estimates like "Task name (2h)"
+        """
+        self._plan_phases = phases
+        return self
+
+    def _generate_track_html(self, track: Track, track_dir: Path) -> str:
+        """Generate track index.html content."""
+        spec_link = '<li><a href="spec.html">📝 Specification</a></li>' if track.has_spec else ''
+        plan_link = '<li><a href="plan.html">📋 Implementation Plan</a></li>' if track.has_plan else ''
+
+        return f'''<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>{track.title}</title>
+    <link rel="stylesheet" href="../../styles.css">
+</head>
+<body>
+    <article id="{track.id}" data-type="track" data-status="{track.status}" data-priority="{track.priority}">
+        <header>
+            <h1>{track.title}</h1>
+            <div class="metadata">
+                <span class="badge status-{track.status}">{track.status.title()}</span>
+                <span class="badge priority-{track.priority}">{track.priority.title()} Priority</span>
+            </div>
+        </header>
+
+        <section data-description>
+            <p>{track.description}</p>
+        </section>
+
+        <nav data-track-components>
+            <h2>Components</h2>
+            <ul>
+                {spec_link}
+                {plan_link}
+            </ul>
+        </nav>
+    </article>
+</body>
+</html>'''
+
+    def create(self) -> Track:
+        """Execute the build and create track+spec+plan."""
+        if not self._title:
+            raise ValueError("Track title is required")
+
+        # Generate track ID
+        track_id = f"track-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
+
+        # Create track
+        track = Track(
+            id=track_id,
+            title=f"Track: {self._title}",
+            description=self._description,
+            priority=self._priority,
+            has_spec=bool(self._spec_data),
+            has_plan=bool(self._plan_phases)
+        )
+
+        # Save track index.html
+        track_dir = Path(".htmlgraph") / "tracks" / track_id
+        track_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate track index HTML
+        track_html = self._generate_track_html(track, track_dir)
+        (track_dir / "index.html").write_text(track_html, encoding="utf-8")
+
+        # Create spec if provided
+        requirements = []
+        if self._spec_data:
+            for i, req in enumerate(self._spec_data.get("requirements", [])):
+                if isinstance(req, tuple):
+                    desc, priority = req
+                else:
+                    desc, priority = req, "must-have"
+
+                requirements.append(Requirement(
+                    id=f"req-{i+1}",
+                    description=desc,
+                    priority=priority
+                ))
+
+            criteria = []
+            for crit in self._spec_data.get("acceptance_criteria", []):
+                if isinstance(crit, tuple):
+                    desc, test_case = crit
+                    criteria.append(AcceptanceCriterion(description=desc, test_case=test_case))
+                else:
+                    criteria.append(AcceptanceCriterion(description=crit))
+
+            spec = Spec(
+                id=f"{track_id}-spec",
+                title=f"{self._title} Specification",
+                track_id=track_id,
+                overview=self._spec_data.get("overview", ""),
+                context=self._spec_data.get("context", ""),
+                requirements=requirements,
+                acceptance_criteria=criteria
+            )
+            (track_dir / "spec.html").write_text(spec.to_html(), encoding="utf-8")
+
+        # Create plan if provided
+        if self._plan_phases:
+            phases = []
+            for i, (phase_name, tasks) in enumerate(self._plan_phases):
+                phase_tasks = []
+                for j, task_desc in enumerate(tasks):
+                    # Parse estimate from task description
+                    estimate = None
+                    if "(" in task_desc and "h)" in task_desc:
+                        match = re.search(r'\((\d+(?:\.\d+)?)\s*h\)', task_desc)
+                        if match:
+                            estimate = float(match.group(1))
+                            task_desc = re.sub(r'\s*\(\d+(?:\.\d+)?\s*h\)', '', task_desc).strip()
+
+                    phase_tasks.append(Task(
+                        id=f"task-{i+1}-{j+1}",
+                        description=task_desc,
+                        estimate_hours=estimate
+                    ))
+
+                phases.append(Phase(
+                    id=f"phase-{i+1}",
+                    name=phase_name,
+                    tasks=phase_tasks
+                ))
+
+            plan = Plan(
+                id=f"{track_id}-plan",
+                title=f"{self._title} Implementation Plan",
+                track_id=track_id,
+                phases=phases
+            )
+            (track_dir / "plan.html").write_text(plan.to_html(), encoding="utf-8")
+
+        print(f"✓ Created track: {track_id}")
+        if self._spec_data:
+            print(f"  - Spec with {len(requirements)} requirements")
+        if self._plan_phases:
+            total_tasks = sum(len(tasks) for _, tasks in self._plan_phases)
+            print(f"  - Plan with {len(self._plan_phases)} phases, {total_tasks} tasks")
+
+        return track
+
+
+class TrackCollection:
+    """Collection interface for tracks with builder support."""
+
+    def __init__(self, sdk: 'SDK'):
+        self._sdk = sdk
+        self.collection_name = "tracks"
+        self.id_prefix = "track"
+
+    def builder(self) -> TrackBuilder:
+        """
+        Create a new track builder with fluent interface.
+
+        Returns:
+            TrackBuilder for method chaining
+
+        Example:
+            track = sdk.tracks.builder() \\
+                .title("Multi-Agent Collaboration") \\
+                .priority("high") \\
+                .with_spec(overview="...") \\
+                .with_plan_phases([...]) \\
+                .create()
+        """
+        return TrackBuilder(self._sdk)