htmlgraph 0.26.23__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)
 
@@ -333,6 +348,11 @@ class SDK:
         # Context analytics interface (Context usage tracking)
         self.context = ContextAnalytics(self)
 
+        # Pattern learning interface (Phase 2: Behavior Pattern Learning)
+        from htmlgraph.analytics.pattern_learning import PatternLearner
+
+        self.pattern_learning = PatternLearner(self._directory)
+
         # Lazy-loaded orchestrator for subagent management
         self._orchestrator: Any = None
 
@@ -448,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)
     # =========================================================================
@@ -776,6 +851,92 @@ class SDK:
             blockers=blockers,
         )
 
+    def continue_from_last(
+        self,
+        agent: str | None = None,
+        auto_create_session: bool = True,
+    ) -> tuple[Any, Any]:
+        """
+        Continue work from the last completed session.
+
+        Loads context from previous session including handoff notes,
+        recommended files, blockers, and recent commits.
+
+        Args:
+            agent: Filter by agent (None = current SDK agent)
+            auto_create_session: Create new session if True
+
+        Returns:
+            Tuple of (new_session, resume_info) or (None, None)
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> session, resume = sdk.continue_from_last()
+            >>> if resume:
+            ...     print(resume.summary)
+            ...     print(resume.next_focus)
+            ...     for file in resume.recommended_files:
+            ...         print(f"  - {file}")
+        """
+        if not agent:
+            agent = self._agent_id
+
+        return self.session_manager.continue_from_last(
+            agent=agent,
+            auto_create_session=auto_create_session,
+        )
+
+    def end_session_with_handoff(
+        self,
+        session_id: str | None = None,
+        summary: str | None = None,
+        next_focus: str | None = None,
+        blockers: list[str] | None = None,
+        keep_context: list[str] | None = None,
+        auto_recommend_context: bool = True,
+    ) -> Any:
+        """
+        End session with handoff information for next session.
+
+        Args:
+            session_id: Session to end (None = active session)
+            summary: What was accomplished
+            next_focus: What should be done next
+            blockers: List of blockers
+            keep_context: List of files to keep context for
+            auto_recommend_context: Auto-recommend files from git
+
+        Returns:
+            Updated Session or None
+
+        Example:
+            >>> sdk.end_session_with_handoff(
+            ...     summary="Completed OAuth integration",
+            ...     next_focus="Implement JWT token refresh",
+            ...     blockers=["Waiting for security review"],
+            ...     keep_context=["src/auth/oauth.py"]
+            ... )
+        """
+        if not session_id:
+            if self._agent_id:
+                active = self.session_manager.get_active_session_for_agent(
+                    self._agent_id
+                )
+            else:
+                active = self.session_manager.get_active_session()
+            if not active:
+                return None
+            session_id = active.id
+
+        return self.session_manager.end_session_with_handoff(
+            session_id=session_id,
+            summary=summary,
+            next_focus=next_focus,
+            blockers=blockers,
+            keep_context=keep_context,
+            auto_recommend_context=auto_recommend_context,
+        )
+
     def start_session(
         self,
         session_id: str | None = None,