htmlgraph 0.26.24__py3-none-any.whl → 0.26.25__py3-none-any.whl

htmlgraph/refs.py

@@ -0,0 +1,343 @@
+"""
+Short reference manager for graph nodes.
+
+Manages persistent mapping of short refs (@f1, @t2, @b5) to full node IDs,
+enabling AI-friendly snapshots and queries.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+
+class RefManager:
+    """
+    Manages short references (@f1, @t1, @b5, etc.) for graph nodes.
+
+    Maintains a persistent refs.json file mapping short refs to full node IDs.
+    Refs are stable across sessions and auto-generated on first access.
+
+    Ref format: @{prefix}{number}
+    Prefixes: f=feature, t=track, b=bug, s=spike, c=chore, e=epic, d=todo
+
+    Example:
+        >>> ref_mgr = RefManager(Path(".htmlgraph"))
+        >>> ref = ref_mgr.generate_ref("feat-a1b2c3d4")
+        >>> print(ref)  # "@f1"
+        >>> full_id = ref_mgr.resolve_ref("@f1")
+        >>> print(full_id)  # "feat-a1b2c3d4"
+    """
+
+    # Map node ID prefix to short ref prefix
+    PREFIX_MAP = {
+        "feat": "f",
+        "trk": "t",
+        "bug": "b",
+        "spk": "s",
+        "chr": "c",
+        "epc": "e",
+        "todo": "d",
+        "phs": "p",
+    }
+
+    # Reverse mapping for type lookup
+    TYPE_MAP = {
+        "f": "feature",
+        "t": "track",
+        "b": "bug",
+        "s": "spike",
+        "c": "chore",
+        "e": "epic",
+        "d": "todo",
+        "p": "phase",
+    }
+
+    def __init__(self, graph_dir: Path):
+        """
+        Initialize RefManager.
+
+        Args:
+            graph_dir: Path to .htmlgraph directory
+        """
+        self.graph_dir = Path(graph_dir)
+        self.refs_file = self.graph_dir / "refs.json"
+        self._refs: dict[str, str] = {}  # Maps: "@f1" -> "feat-a1b2c3d4"
+        self._reverse_refs: dict[str, str] = {}  # Maps: "feat-a1b2c3d4" -> "@f1"
+        self._load()
+
+    def _load(self) -> None:
+        """Load refs.json into memory."""
+        if not self.refs_file.exists():
+            self._refs = {}
+            self._reverse_refs = {}
+            return
+
+        try:
+            with open(self.refs_file, encoding="utf-8") as f:
+                data = json.load(f)
+                self._refs = data.get("refs", {})
+
+            # Build reverse mapping
+            self._reverse_refs = {v: k for k, v in self._refs.items()}
+        except (json.JSONDecodeError, OSError) as e:
+            # Corrupted file - start fresh
+            import logging
+
+            logging.warning(f"Failed to load refs.json: {e}. Starting fresh.")
+            self._refs = {}
+            self._reverse_refs = {}
+
+    def _save(self) -> None:
+        """Save refs to refs.json."""
+        # Ensure directory exists
+        self.graph_dir.mkdir(parents=True, exist_ok=True)
+
+        data = {
+            "refs": self._refs,
+            "version": 1,
+            "regenerated_at": datetime.now().isoformat(),
+        }
+
+        try:
+            with open(self.refs_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+        except OSError as e:
+            import logging
+
+            logging.error(f"Failed to save refs.json: {e}")
+
+    def _parse_node_type(self, node_id: str) -> str | None:
+        """
+        Extract node type prefix from node ID.
+
+        Args:
+            node_id: Full node ID like "feat-a1b2c3d4"
+
+        Returns:
+            Node type prefix (e.g., "feat") or None if invalid
+        """
+        if "-" not in node_id:
+            return None
+
+        prefix = node_id.split("-", 1)[0]
+        return prefix if prefix in self.PREFIX_MAP else None
+
+    def _next_ref_number(self, prefix: str) -> int:
+        """
+        Get next available ref number for a type.
+
+        Args:
+            prefix: Short ref prefix (e.g., "f", "t", "b")
+
+        Returns:
+            Next available number (1, 2, 3, ...)
+        """
+        # Find all refs with this prefix
+        existing = [int(ref[2:]) for ref in self._refs if ref.startswith(f"@{prefix}")]
+        return max(existing, default=0) + 1
+
+    def generate_ref(self, node_id: str) -> str:
+        """
+        Generate a short ref for a node ID.
+
+        This method is idempotent - calling it multiple times with the same
+        node_id returns the same ref without creating duplicates.
+
+        Args:
+            node_id: Full node ID like "feat-a1b2c3d4"
+
+        Returns:
+            Short ref like "@f1"
+
+        Raises:
+            ValueError: If node_id has invalid format
+
+        Example:
+            >>> ref = ref_mgr.generate_ref("feat-abc123")
+            >>> print(ref)  # "@f1"
+            >>> # Second call returns same ref
+            >>> ref2 = ref_mgr.generate_ref("feat-abc123")
+            >>> assert ref == ref2
+        """
+        # Check if already has ref (idempotent)
+        if node_id in self._reverse_refs:
+            return self._reverse_refs[node_id]
+
+        # Parse node type
+        node_prefix = self._parse_node_type(node_id)
+        if not node_prefix:
+            raise ValueError(f"Invalid node ID format: {node_id}")
+
+        # Get short prefix
+        short_prefix = self.PREFIX_MAP[node_prefix]
+
+        # Generate next ref
+        number = self._next_ref_number(short_prefix)
+        short_ref = f"@{short_prefix}{number}"
+
+        # Store mappings
+        self._refs[short_ref] = node_id
+        self._reverse_refs[node_id] = short_ref
+
+        # Persist
+        self._save()
+
+        return short_ref
+
+    def get_ref(self, node_id: str) -> str | None:
+        """
+        Get existing ref for a node ID (create if not exist).
+
+        Args:
+            node_id: Full node ID like "feat-a1b2c3d4"
+
+        Returns:
+            Short ref like "@f1", or None if node_id invalid
+
+        Example:
+            >>> ref = ref_mgr.get_ref("feat-abc123")
+            >>> # Creates ref if doesn't exist
+        """
+        # Return existing ref
+        if node_id in self._reverse_refs:
+            return self._reverse_refs[node_id]
+
+        # Generate new ref if valid node ID
+        try:
+            return self.generate_ref(node_id)
+        except ValueError:
+            return None
+
+    def resolve_ref(self, short_ref: str) -> str | None:
+        """
+        Resolve short ref to full node ID.
+
+        Args:
+            short_ref: "@f1", "@t2", etc.
+
+        Returns:
+            Full node ID or None if not found
+
+        Example:
+            >>> full_id = ref_mgr.resolve_ref("@f1")
+            >>> print(full_id)  # "feat-abc123"
+        """
+        return self._refs.get(short_ref)
+
+    def get_all_refs(self) -> dict[str, str]:
+        """
+        Return all refs.
+
+        Returns:
+            Dict mapping short refs to full IDs: {"@f1": "feat-a1b2c3d4", ...}
+        """
+        return self._refs.copy()
+
+    def get_refs_by_type(self, node_type: str) -> list[tuple[str, str]]:
+        """
+        Get all refs for a specific type.
+
+        Args:
+            node_type: "feature", "track", "bug", "spike", "chore", "epic", "todo", "phase"
+
+        Returns:
+            List of (short_ref, full_id) tuples sorted by ref number
+
+        Example:
+            >>> feature_refs = ref_mgr.get_refs_by_type("feature")
+            >>> for ref, full_id in feature_refs:
+            ...     print(f"{ref} -> {full_id}")
+        """
+        # Get prefix for this type
+        prefix = None
+        for short_prefix, type_name in self.TYPE_MAP.items():
+            if type_name == node_type:
+                prefix = short_prefix
+                break
+
+        if not prefix:
+            return []
+
+        # Filter refs by prefix
+        matching = [
+            (ref, full_id)
+            for ref, full_id in self._refs.items()
+            if ref.startswith(f"@{prefix}")
+        ]
+
+        # Sort by ref number
+        def sort_key(item: tuple[str, str]) -> int:
+            ref = item[0]
+            try:
+                return int(ref[2:])  # Extract number after "@f"
+            except (ValueError, IndexError):
+                return 0
+
+        return sorted(matching, key=sort_key)
+
+    def rebuild_refs(self) -> None:
+        """
+        Rebuild refs from all .htmlgraph/ files (recovery tool).
+
+        Scans all collection directories (features/, tracks/, bugs/, etc.)
+        and rebuilds refs.json from scratch. Preserves existing refs where
+        possible to maintain stability.
+
+        This is a recovery tool for when refs.json is corrupted or deleted.
+
+        Example:
+            >>> ref_mgr.rebuild_refs()
+            >>> # Refs regenerated from file system
+        """
+        # Save current refs for preservation
+        old_refs = self._refs.copy()
+
+        # Clear in-memory refs
+        self._refs = {}
+        self._reverse_refs = {}
+
+        # Scan all collection directories
+        collections = [
+            "features",
+            "tracks",
+            "bugs",
+            "spikes",
+            "chores",
+            "epics",
+            "todos",
+            "phases",
+        ]
+
+        for collection in collections:
+            collection_dir = self.graph_dir / collection
+            if not collection_dir.exists():
+                continue
+
+            # Scan HTML files
+            for html_file in collection_dir.glob("*.html"):
+                # Extract node ID from filename (without .html)
+                node_id = html_file.stem
+
+                # Skip if invalid format
+                if not self._parse_node_type(node_id):
+                    continue
+
+                # Try to preserve existing ref
+                if node_id in {v for v in old_refs.values()}:
+                    # Find old ref
+                    old_ref = next(
+                        (k for k, v in old_refs.items() if v == node_id), None
+                    )
+                    if old_ref:
+                        # Preserve old ref
+                        self._refs[old_ref] = node_id
+                        self._reverse_refs[node_id] = old_ref
+                        continue
+
+                # Generate new ref
+                self.generate_ref(node_id)
+
+        # Save to disk
+        self._save()

htmlgraph/sdk.py

@@ -41,7 +41,7 @@ from __future__ import annotations
 
 import os
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from htmlgraph.agent_detection import detect_agent_name
 from htmlgraph.agents import AgentInterface
@@ -321,6 +321,21 @@ class SDK:
         (self._directory / "todos").mkdir(exist_ok=True)
         (self._directory / "task-delegations").mkdir(exist_ok=True)
 
+        # Initialize RefManager and set on all collections
+        from htmlgraph.refs import RefManager
+
+        self.refs = RefManager(self._directory)
+
+        # Set ref manager on all work item collections
+        self.features.set_ref_manager(self.refs)
+        self.bugs.set_ref_manager(self.refs)
+        self.chores.set_ref_manager(self.refs)
+        self.spikes.set_ref_manager(self.refs)
+        self.epics.set_ref_manager(self.refs)
+        self.phases.set_ref_manager(self.refs)
+        self.tracks.set_ref_manager(self.refs)
+        self.todos.set_ref_manager(self.refs)
+
         # Analytics interface (Phase 2: Work Type Analytics)
         self.analytics = Analytics(self)
 
@@ -453,6 +468,61 @@ class SDK:
             return self._session_warning.get_status()
         return {"dismissed": True, "show_count": 0}
 
+    def ref(self, short_ref: str) -> Node | None:
+        """
+        Resolve a short ref to a Node object.
+
+        Short refs are stable identifiers like @f1, @t2, @b5 that map to
+        full node IDs. This method resolves the short ref and fetches the
+        corresponding node from the appropriate collection.
+
+        Args:
+            short_ref: Short ref like "@f1", "@t2", "@b5", etc.
+
+        Returns:
+            Node object or None if not found
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> feature = sdk.ref("@f1")
+            >>> if feature:
+            ...     print(feature.title)
+            ...     feature.status = "done"
+            ...     sdk.features.update(feature)
+        """
+        # Resolve short ref to full ID
+        full_id = self.refs.resolve_ref(short_ref)
+        if not full_id:
+            return None
+
+        # Determine type from ref prefix and fetch from appropriate collection
+        if len(short_ref) < 2:
+            return None
+
+        prefix = short_ref[1]  # Get letter after @
+
+        # Map prefix to collection
+        collection_map = {
+            "f": self.features,
+            "t": self.tracks,
+            "b": self.bugs,
+            "s": self.spikes,
+            "c": self.chores,
+            "e": self.epics,
+            "d": self.todos,
+            "p": self.phases,
+        }
+
+        collection = collection_map.get(prefix)
+        if not collection:
+            return None
+
+        # Get node from collection
+        if hasattr(collection, "get"):
+            return cast(Node | None, collection.get(full_id))
+
+        return None
+
     # =========================================================================
     # SQLite Database Integration (Phase 2)
     # =========================================================================

htmlgraph/session_manager.py

@@ -929,13 +929,7 @@ class SessionManager:
         session.handoff_notes = handoff_data["handoff_notes"]
         session.recommended_next = handoff_data["recommended_next"]
         session.blockers = handoff_data["blockers"]
-
-        # Store recommended_context as JSON-serializable list
-        # (Session model expects list[str], converter will handle serialization)
-        if hasattr(session, "__dict__"):
-            session.__dict__["recommended_context"] = handoff_data[
-                "recommended_context"
-            ]
+        session.recommended_context = handoff_data["recommended_context"]
 
         # Persist handoff data to database before ending session
         self.session_converter.save(session)

htmlgraph/sessions/handoff.py

@@ -613,6 +613,9 @@ class HandoffTracker:
         handoff_id = generate_id("hand")
 
         if self.db and self.db.connection:
+            # Ensure session exists in database (handles FK constraint)
+            self.db._ensure_session_exists(from_session_id)
+
             cursor = self.db.connection.cursor()
             cursor.execute(
                 """
@@ -649,6 +652,9 @@ class HandoffTracker:
             return False
 
         try:
+            # Ensure to_session exists in database (handles FK constraint)
+            self.db._ensure_session_exists(to_session_id)
+
             cursor = self.db.connection.cursor()
             cursor.execute(
                 """

htmlgraph/track_builder.py

@@ -31,6 +31,18 @@ class TrackCollection:
         self.collection_name = "tracks"  # For backward compatibility
         self.id_prefix = "track"
         self._graph: HtmlGraph | None = None  # Lazy-loaded
+        self._ref_manager: Any = None  # Set by SDK during initialization
+
+    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 _ensure_graph(self) -> HtmlGraph:
         """Lazy-load the graph for tracks with multi-pattern support."""

{htmlgraph-0.26.24.dist-info → htmlgraph-0.26.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.26.24
+Version: 0.26.25
 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