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

htmlgraph/setup.py

@@ -8,13 +8,10 @@ Automates setup of HtmlGraph for different AI CLI platforms:
 - Gemini CLI (extension installation)
 """
 
-import json
-import os
 import shutil
 import subprocess
-import sys
 from pathlib import Path
-from typing import Optional
+from typing import Any
 
 
 def check_command_exists(command: str) -> bool:
@@ -22,8 +19,11 @@ def check_command_exists(command: str) -> bool:
     return shutil.which(command) is not None
 
 
-def run_command(cmd: list[str], capture=False, check=True) -> subprocess.CompletedProcess:
+def run_command(
+    cmd: list[str], capture: bool = False, check: bool = True
+) -> subprocess.CompletedProcess[Any]:
     """Run a shell command."""
+    result: subprocess.CompletedProcess[Any]
     try:
         if capture:
             result = subprocess.run(cmd, capture_output=True, text=True, check=check)
@@ -38,7 +38,7 @@ def run_command(cmd: list[str], capture=False, check=True) -> subprocess.Complet
         raise
 
 
-def setup_claude(args):
+def setup_claude(args: Any) -> bool:
     """Set up HtmlGraph for Claude Code."""
     print("🔧 Setting up HtmlGraph for Claude Code...")
     print()
@@ -74,7 +74,9 @@ def setup_claude(args):
 
             # Try to get version
             if "@" in result.stdout:
-                version_line = [line for line in result.stdout.split("\n") if "htmlgraph" in line]
+                version_line = [
+                    line for line in result.stdout.split("\n") if "htmlgraph" in line
+                ]
                 if version_line:
                     print(f"   {version_line[0].strip()}")
         else:
@@ -99,7 +101,7 @@ def setup_claude(args):
     return True
 
 
-def setup_codex(args):
+def setup_codex(args: Any) -> bool:
     """Set up HtmlGraph for Codex CLI."""
     print("🔧 Setting up HtmlGraph for Codex CLI...")
     print()
@@ -142,7 +144,7 @@ def setup_codex(args):
         else:
             print("⚠️  SKILL.md not found - skill may be incomplete")
     else:
-        print(f"\n⚠️  HtmlGraph skill not installed")
+        print("\n⚠️  HtmlGraph skill not installed")
         print("\n📥 Installation options:")
 
         # Check if we're in the HtmlGraph repo
@@ -167,7 +169,9 @@ def setup_codex(args):
         print(f"   cp -r htmlgraph/packages/codex-skill {htmlgraph_skill_dir}")
 
         print("\n   Option 3: Download manually:")
-        print("   https://github.com/Shakes-tzd/htmlgraph/tree/main/packages/codex-skill")
+        print(
+            "   https://github.com/Shakes-tzd/htmlgraph/tree/main/packages/codex-skill"
+        )
 
     # Check MCP configuration
     print("\n🔌 Checking MCP configuration...")
@@ -190,7 +194,7 @@ def setup_codex(args):
     return True
 
 
-def setup_gemini(args):
+def setup_gemini(args: Any) -> bool:
     """Set up HtmlGraph for Gemini CLI."""
     print("🔧 Setting up HtmlGraph for Gemini CLI...")
     print()
@@ -207,7 +211,9 @@ def setup_gemini(args):
     print("\n🎯 Checking for HtmlGraph extension...")
 
     try:
-        result = run_command(["gemini", "extensions", "list"], capture=True, check=False)
+        result = run_command(
+            ["gemini", "extensions", "list"], capture=True, check=False
+        )
         if result.returncode == 0 and "htmlgraph" in result.stdout.lower():
             print("✅ HtmlGraph extension already installed")
         else:
@@ -217,19 +223,28 @@ def setup_gemini(args):
             # Check if we're in the HtmlGraph repo
             repo_extension = Path.cwd() / "packages" / "gemini-extension"
             if repo_extension.exists():
-                print(f"\n   Option 1: Install from this repo:")
+                print("\n   Option 1: Install from this repo:")
                 print(f"   gemini extensions install {repo_extension.absolute()}")
 
                 if args.auto_install:
                     print("\n   Auto-installing...")
                     try:
-                        run_command(["gemini", "extensions", "install", str(repo_extension.absolute())])
+                        run_command(
+                            [
+                                "gemini",
+                                "extensions",
+                                "install",
+                                str(repo_extension.absolute()),
+                            ]
+                        )
                         print("   ✅ Extension installed")
                     except Exception as e:
                         print(f"   ❌ Failed to install extension: {e}")
 
             print("\n   Option 2: Install from GitHub:")
-            print("   gemini extensions install https://github.com/Shakes-tzd/htmlgraph/tree/main/packages/gemini-extension")
+            print(
+                "   gemini extensions install https://github.com/Shakes-tzd/htmlgraph/tree/main/packages/gemini-extension"
+            )
 
             print("\n   Option 3: Create manually:")
             print("   gemini extensions create htmlgraph-tracker")
@@ -252,7 +267,7 @@ def setup_gemini(args):
     return True
 
 
-def setup_all(args):
+def setup_all(args: Any) -> bool:
     """Set up HtmlGraph for all supported platforms."""
     print("🚀 Setting up HtmlGraph for all supported platforms...")
     print("=" * 60)
@@ -287,7 +302,9 @@ def setup_all(args):
     print("=" * 60)
     for platform, success in results.items():
         status = "✅" if success else "⚠️ "
-        print(f"{status} {platform.upper()}: {'Ready' if success else 'Needs attention'}")
+        print(
+            f"{status} {platform.upper()}: {'Ready' if success else 'Needs attention'}"
+        )
     print()
 
     return all(results.values())

htmlgraph/spike_index.py

@@ -0,0 +1,143 @@
+"""
+Lightweight index for tracking active auto-generated spikes.
+
+This avoids the expensive operation of scanning all spike files on SessionManager init.
+Instead, we maintain a simple JSON index that tracks only active auto-spikes.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ActiveAutoSpikeIndex:
+    """
+    Fast index for tracking active auto-generated spikes (session-init, transition, conversation-init).
+
+    This is much faster than scanning all spike files on startup.
+    The index is a simple JSON file that maps spike_id -> metadata.
+    """
+
+    def __init__(self, graph_dir: Path):
+        """
+        Initialize the index.
+
+        Args:
+            graph_dir: .htmlgraph directory
+        """
+        self.graph_dir = Path(graph_dir)
+        self.index_path = self.graph_dir / "active-auto-spikes.json"
+        self._data: dict[str, dict[str, Any]] = {}
+        self._loaded = False
+
+    def load(self) -> None:
+        """Load index from disk (lazy)."""
+        if self._loaded:
+            return
+
+        if self.index_path.exists():
+            try:
+                with open(self.index_path) as f:
+                    self._data = json.load(f)
+            except (json.JSONDecodeError, OSError) as e:
+                logger.warning(
+                    f"Failed to load active-auto-spikes index: {e}. Starting fresh."
+                )
+                self._data = {}
+        else:
+            self._data = {}
+
+        self._loaded = True
+
+    def save(self) -> None:
+        """Save index to disk."""
+        try:
+            with open(self.index_path, "w") as f:
+                json.dump(self._data, f, indent=2)
+        except OSError as e:
+            logger.warning(f"Failed to save active-auto-spikes index: {e}")
+
+    def add(
+        self, spike_id: str, spike_subtype: str, session_id: str | None = None
+    ) -> None:
+        """
+        Add an active auto-spike to the index.
+
+        Args:
+            spike_id: Spike ID
+            spike_subtype: Spike subtype (session-init, transition, conversation-init)
+            session_id: Optional session ID
+        """
+        self.load()
+        self._data[spike_id] = {
+            "spike_subtype": spike_subtype,
+            "session_id": session_id,
+        }
+        self.save()
+
+    def remove(self, spike_id: str) -> None:
+        """
+        Remove a spike from the index (when completed or deleted).
+
+        Args:
+            spike_id: Spike ID to remove
+        """
+        self.load()
+        if spike_id in self._data:
+            del self._data[spike_id]
+            self.save()
+
+    def get_all(self) -> set[str]:
+        """
+        Get all active auto-spike IDs.
+
+        Returns:
+            Set of spike IDs
+        """
+        self.load()
+        return set(self._data.keys())
+
+    def clear(self) -> None:
+        """Clear the index (for testing or cleanup)."""
+        self._data = {}
+        self.save()
+
+    def rebuild_from_disk(self) -> int:
+        """
+        Rebuild the index by scanning all spike files on disk.
+
+        This is the expensive operation we're trying to avoid during normal init.
+        Only call this when necessary (e.g., after manual file edits or corruption).
+
+        Returns:
+            Number of active auto-spikes found
+        """
+        from htmlgraph.converter import NodeConverter
+
+        spikes_dir = self.graph_dir / "spikes"
+        if not spikes_dir.exists():
+            self.clear()
+            return 0
+
+        spike_converter = NodeConverter(spikes_dir)
+        self._data = {}
+
+        # Scan all spikes for active auto-generated ones
+        for spike in spike_converter.load_all():
+            if (
+                spike.type == "spike"
+                and getattr(spike, "auto_generated", False)
+                and getattr(spike, "spike_subtype", None)
+                in ("session-init", "transition", "conversation-init")
+                and spike.status == "in-progress"
+            ):
+                self._data[spike.id] = {
+                    "spike_subtype": spike.spike_subtype,
+                    "session_id": getattr(spike, "session_id", None),
+                }
+
+        self.save()
+        return len(self._data)

htmlgraph/sync_docs.py

@@ -15,8 +15,6 @@ Usage:
 import argparse
 import sys
 from pathlib import Path
-from typing import Dict, List
-
 
 # Platform-specific file templates
 PLATFORM_TEMPLATES = {
@@ -97,9 +95,9 @@ def generate_platform_file(platform: str, project_root: Path) -> str:
             f"Unknown platform: {platform}. Available: {', '.join(PLATFORM_TEMPLATES.keys())}"
         )
 
-    content = f"""# {template['title']}
+    content = f"""# {template["title"]}
 
-**Platform-specific instructions for {template['platform_name']} AI agents.**
+**Platform-specific instructions for {template["platform_name"]} AI agents.**
 
 ---
 
@@ -117,13 +115,13 @@ The main AGENTS.md file contains:
 
 ---
 
-## {template['platform_name']}-Specific Notes
+## {template["platform_name"]}-Specific Notes
 
-{template['notes']}
+{template["notes"]}
 
 ---
 
-## Commands Available in {template['platform_name']}
+## Commands Available in {template["platform_name"]}
 
 All HtmlGraph commands are available through the extension/plugin:
 
@@ -160,7 +158,7 @@ def check_file_references_agents(filepath: Path) -> bool:
     return "AGENTS.md" in content
 
 
-def check_all_files(project_root: Path) -> Dict[str, bool]:
+def check_all_files(project_root: Path) -> dict[str, bool]:
     """Check all platform files for AGENTS.md references."""
     results = {}
 
@@ -177,7 +175,8 @@ def check_all_files(project_root: Path) -> Dict[str, bool]:
 
     # Check package-specific skill files (actual locations)
     skill_files = {
-        "claude-plugin": project_root / "packages/claude-plugin/skills/htmlgraph-tracker/SKILL.md",
+        "claude-plugin": project_root
+        / "packages/claude-plugin/skills/htmlgraph-tracker/SKILL.md",
         "gemini-extension": project_root / "packages/gemini-extension/GEMINI.md",
         "codex-skill": project_root / "packages/codex-skill/SKILL.md",
     }
@@ -190,7 +189,7 @@ def check_all_files(project_root: Path) -> Dict[str, bool]:
     return results
 
 
-def sync_all_files(project_root: Path, dry_run: bool = False) -> List[str]:
+def sync_all_files(project_root: Path, dry_run: bool = False) -> list[str]:
     """Synchronize all platform files to reference AGENTS.md."""
     changes = []
 
@@ -222,7 +221,7 @@ def sync_all_files(project_root: Path, dry_run: bool = False) -> List[str]:
     return changes
 
 
-def main():
+def main() -> int:
     parser = argparse.ArgumentParser(
         description="Synchronize AI agent memory files for a project"
     )
@@ -291,14 +290,12 @@ def main():
             filepath = project_root / template["filename"]
 
             if filepath.exists() and not args.force:
-                print(
-                    f"⚠️  {filepath.name} already exists. Use --force to overwrite."
-                )
+                print(f"⚠️  {filepath.name} already exists. Use --force to overwrite.")
                 return 1
 
             filepath.write_text(content)
             print(f"✅ Created: {filepath}")
-            print(f"\nThe file references AGENTS.md for core documentation.")
+            print("\nThe file references AGENTS.md for core documentation.")
             return 0
 
         except ValueError as e: