htmlgraph 0.22.0__py3-none-any.whl → 0.23.1__py3-none-any.whl

htmlgraph/cli.py

@@ -8,6 +8,11 @@ Usage:
     htmlgraph status [--dir DIR]
     htmlgraph query SELECTOR [--dir DIR]
 
+Claude Code Integration:
+    htmlgraph claude                    # Start Claude Code
+    htmlgraph claude --init             # Start with orchestrator system prompt (recommended)
+    htmlgraph claude --continue         # Resume last Claude Code session
+
 Session Management:
     htmlgraph session start [--id ID] [--agent AGENT]
     htmlgraph session end ID [--notes NOTES] [--recommend NEXT] [--blocker BLOCKER]
@@ -111,9 +116,9 @@ def cmd_install_gemini_extension(args: argparse.Namespace) -> None:
 
 def cmd_serve(args: argparse.Namespace) -> None:
     """Start the HtmlGraph server."""
-    from htmlgraph.server import serve
+    from htmlgraph.operations import start_server
 
-    serve(
+    start_server(
         port=args.port,
         graph_dir=args.graph_dir,
         static_dir=args.static_dir,
@@ -122,10 +127,14 @@ def cmd_serve(args: argparse.Namespace) -> None:
         auto_port=args.auto_port,
     )
 
+    # The start_server operation already handles all output and blocks
+    # No additional CLI formatting needed
+
 
 def cmd_init(args: argparse.Namespace) -> None:
     """Initialize a new .htmlgraph directory."""
     import shutil
+    from contextlib import nullcontext
 
     from htmlgraph.analytics_index import AnalyticsIndex
     from htmlgraph.server import HtmlGraphAPIHandler
@@ -160,38 +169,33 @@ def cmd_init(args: argparse.Namespace) -> None:
         agent_name = "claude"
         generate_docs = True  # Always generate in non-interactive mode
 
-    graph_dir = Path(args.dir) / ".htmlgraph"
-    graph_dir.mkdir(parents=True, exist_ok=True)
-
-    for collection in HtmlGraphAPIHandler.COLLECTIONS:
-        (graph_dir / collection).mkdir(exist_ok=True)
-
-    # Event stream directory (Git-friendly source of truth)
-    events_dir = graph_dir / "events"
-    events_dir.mkdir(exist_ok=True)
-    if not args.no_events_keep:
-        keep = events_dir / ".gitkeep"
-        if not keep.exists():
-            keep.write_text("", encoding="utf-8")
-
-    # Copy stylesheet
-    styles_src = Path(__file__).parent / "styles.css"
-    styles_dest = graph_dir / "styles.css"
-    if styles_src.exists() and not styles_dest.exists():
-        styles_dest.write_text(styles_src.read_text())
-
-    # Create default index.html if not exists
-    index_path = Path(args.dir) / "index.html"
-    if not index_path.exists():
-        create_default_index(index_path)
-
-    # Create analytics cache DB (rebuildable; typically gitignored)
-    if not args.no_index:
+    def init_progress() -> tuple[Any | None, Any | None]:
+        if args.quiet or getattr(args, "format", "text") != "text":
+            return None, None
         try:
-            AnalyticsIndex(graph_dir / "index.sqlite").ensure_schema()
+            from rich.console import Console
+            from rich.progress import (
+                BarColumn,
+                Progress,
+                SpinnerColumn,
+                TextColumn,
+                TimeElapsedColumn,
+            )
         except Exception:
-            # Never fail init because of analytics cache.
-            pass
+            return None, None
+        console = Console()
+        progress = Progress(
+            SpinnerColumn(),
+            TextColumn("{task.description}"),
+            BarColumn(),
+            TimeElapsedColumn(),
+            console=console,
+            transient=True,
+        )
+        return progress, console
+
+    graph_dir = Path(args.dir) / ".htmlgraph"
+    events_dir = graph_dir / "events"
 
     def ensure_gitignore_entries(project_dir: Path, lines: list[str]) -> None:
         if args.no_update_gitignore:
@@ -218,19 +222,12 @@ def cmd_init(args: argparse.Namespace) -> None:
             # Don't fail init on .gitignore issues.
             pass
 
-    ensure_gitignore_entries(
-        Path(args.dir),
-        [
-            ".htmlgraph/index.sqlite",
-            ".htmlgraph/index.sqlite-wal",
-            ".htmlgraph/index.sqlite-shm",
-            ".htmlgraph/git-hook-errors.log",
-        ],
-    )
+    progress, progress_console = init_progress()
 
-    # Ensure versioned hook scripts exist (installation into .git/hooks is optional)
-    hooks_dir = graph_dir / "hooks"
-    hooks_dir.mkdir(exist_ok=True)
+    def status_context(message: str) -> Any:
+        if progress_console is None:
+            return nullcontext()
+        return progress_console.status(message)
 
     # Hook templates (used when htmlgraph is installed without this repo layout).
     post_commit = """#!/bin/bash
@@ -443,26 +440,77 @@ fi
 exit 0
 """
 
-    def ensure_hook_file(hook_name: str, hook_content: str) -> Path:
-        hook_dest = hooks_dir / f"{hook_name}.sh"
-        if not hook_dest.exists():
-            hook_dest.write_text(hook_content)
-        try:
-            hook_dest.chmod(0o755)
-        except Exception:
-            pass
-        return hook_dest
-
-    hook_files = {
-        "pre-commit": ensure_hook_file("pre-commit", pre_commit),
-        "post-commit": ensure_hook_file("post-commit", post_commit),
-        "post-checkout": ensure_hook_file("post-checkout", post_checkout),
-        "post-merge": ensure_hook_file("post-merge", post_merge),
-        "pre-push": ensure_hook_file("pre-push", pre_push),
-    }
+    hook_files: dict[str, Path] = {}
 
-    # Generate documentation files from templates
-    if generate_docs:
+    def create_graph_dirs() -> None:
+        graph_dir.mkdir(parents=True, exist_ok=True)
+        for collection in HtmlGraphAPIHandler.COLLECTIONS:
+            (graph_dir / collection).mkdir(exist_ok=True)
+
+    def create_events_dir() -> None:
+        events_dir.mkdir(exist_ok=True)
+        if not args.no_events_keep:
+            keep = events_dir / ".gitkeep"
+            if not keep.exists():
+                keep.write_text("", encoding="utf-8")
+
+    def copy_assets() -> None:
+        styles_src = Path(__file__).parent / "styles.css"
+        styles_dest = graph_dir / "styles.css"
+        if styles_src.exists() and not styles_dest.exists():
+            styles_dest.write_text(styles_src.read_text())
+
+        index_path = Path(args.dir) / "index.html"
+        if not index_path.exists():
+            create_default_index(index_path)
+
+    def init_analytics_cache() -> None:
+        if args.no_index:
+            return
+        with status_context("Initializing analytics cache..."):
+            try:
+                AnalyticsIndex(graph_dir / "index.sqlite").ensure_schema()
+            except Exception:
+                # Never fail init because of analytics cache.
+                pass
+
+    def update_gitignore() -> None:
+        ensure_gitignore_entries(
+            Path(args.dir),
+            [
+                ".htmlgraph/index.sqlite",
+                ".htmlgraph/index.sqlite-wal",
+                ".htmlgraph/index.sqlite-shm",
+                ".htmlgraph/git-hook-errors.log",
+            ],
+        )
+
+    def create_hook_templates() -> None:
+        nonlocal hook_files
+        hooks_dir = graph_dir / "hooks"
+        hooks_dir.mkdir(exist_ok=True)
+
+        def ensure_hook_file(hook_name: str, hook_content: str) -> Path:
+            hook_dest = hooks_dir / f"{hook_name}.sh"
+            if not hook_dest.exists():
+                hook_dest.write_text(hook_content)
+            try:
+                hook_dest.chmod(0o755)
+            except Exception:
+                pass
+            return hook_dest
+
+        hook_files = {
+            "pre-commit": ensure_hook_file("pre-commit", pre_commit),
+            "post-commit": ensure_hook_file("post-commit", post_commit),
+            "post-checkout": ensure_hook_file("post-checkout", post_checkout),
+            "post-merge": ensure_hook_file("post-merge", post_merge),
+            "pre-push": ensure_hook_file("pre-push", pre_push),
+        }
+
+    def generate_docs_step() -> None:
+        if not generate_docs:
+            return
 
         def render_template(
             template_path: Path, replacements: dict[str, str]
@@ -483,7 +531,7 @@ exit 0
             from htmlgraph import __version__
 
             version = __version__
-        except:
+        except Exception:
             version = "unknown"
 
         replacements = {
@@ -519,17 +567,9 @@ exit 0
                 gemini_dest.write_text(content, encoding="utf-8")
                 print(f"✓ Generated: {gemini_dest}")
 
-    print(f"\nInitialized HtmlGraph in {graph_dir}")
-    print(f"Collections: {', '.join(HtmlGraphAPIHandler.COLLECTIONS)}")
-    print("\nStart server with: htmlgraph serve")
-    if not args.no_index:
-        print(
-            f"Analytics cache: {graph_dir / 'index.sqlite'} (rebuildable; typically gitignored)"
-        )
-    print(f"Events: {events_dir}/ (append-only JSONL)")
-
-    # Install Git hooks if requested
-    if args.install_hooks:
+    def install_hooks_step() -> None:
+        if not args.install_hooks:
+            return
         git_dir = Path(args.dir) / ".git"
         if not git_dir.exists():
             print("\n⚠️  Warning: No .git directory found. Git hooks not installed.")
@@ -606,6 +646,46 @@ fi
 
         print("\nGit events will now be logged to HtmlGraph automatically.")
 
+    steps: list[tuple[str, Any]] = [
+        ("Create .htmlgraph directories", create_graph_dirs),
+        ("Create event log directory", create_events_dir),
+        ("Update .gitignore", update_gitignore),
+        ("Prepare git hook templates", create_hook_templates),
+        ("Copy default assets", copy_assets),
+    ]
+    if not args.no_index:
+        steps.append(("Initialize analytics cache", init_analytics_cache))
+    if generate_docs:
+        steps.append(("Generate documentation", generate_docs_step))
+    if args.install_hooks:
+        steps.append(("Install git hooks", install_hooks_step))
+
+    def run_steps(step_list: list[tuple[str, Any]]) -> None:
+        if progress is None:
+            for _, fn in step_list:
+                fn()
+            return
+
+        with progress:
+            task_id = progress.add_task(
+                "Initializing HtmlGraph...", total=len(step_list)
+            )
+            for description, fn in step_list:
+                progress.update(task_id, description=description)
+                fn()
+                progress.advance(task_id)
+
+    run_steps(steps)
+
+    print(f"\nInitialized HtmlGraph in {graph_dir}")
+    print(f"Collections: {', '.join(HtmlGraphAPIHandler.COLLECTIONS)}")
+    print("\nStart server with: htmlgraph serve")
+    if not args.no_index:
+        print(
+            f"Analytics cache: {graph_dir / 'index.sqlite'} (rebuildable; typically gitignored)"
+        )
+    print(f"Events: {events_dir}/ (append-only JSONL)")
+
 
 def cmd_install_hooks(args: argparse.Namespace) -> None:
     """Install Git hooks for automatic tracking."""
@@ -2358,22 +2438,15 @@ def cmd_events_export(args: argparse.Namespace) -> None:
 
 def cmd_index_rebuild(args: argparse.Namespace) -> None:
     """Rebuild the SQLite analytics index from JSONL event logs."""
-    from htmlgraph.analytics_index import AnalyticsIndex
-    from htmlgraph.event_log import JsonlEventLog
+    from htmlgraph.operations import rebuild_index
 
     graph_dir = Path(args.graph_dir)
-    events_dir = graph_dir / "events"
-    db_path = graph_dir / "index.sqlite"
-
-    log = JsonlEventLog(events_dir)
-    index = AnalyticsIndex(db_path)
 
-    events = (event for _, event in log.iter_events())
-    result = index.rebuild_from_events(events)
+    result = rebuild_index(graph_dir=graph_dir)
 
-    print(f"DB: {db_path}")
-    print(f"Inserted: {result['inserted']}")
-    print(f"Skipped:  {result['skipped']}")
+    print(f"DB: {result.db_path}")
+    print(f"Inserted: {result.inserted}")
+    print(f"Skipped:  {result.skipped}")
 
 
 def cmd_watch(args: argparse.Namespace) -> None:
@@ -3512,6 +3585,106 @@ def create_default_index(path: Path) -> None:
     )
 
 
+def cmd_claude(args: argparse.Namespace) -> None:
+    """Start Claude Code with orchestrator prompt."""
+    import textwrap
+
+    try:
+        if args.init:
+            # Load optimized orchestrator system prompt
+            prompt_file = Path(__file__).parent / "orchestrator_system_prompt.txt"
+
+            if prompt_file.exists():
+                system_prompt = prompt_file.read_text(encoding="utf-8")
+            else:
+                # Fallback: provide minimal orchestrator guidance
+                system_prompt = textwrap.dedent(
+                    """
+                    You are an AI orchestrator for HtmlGraph project development.
+
+                    CRITICAL DIRECTIVES:
+                    1. DELEGATE to subagents - do not implement directly
+                    2. CREATE work items before delegating (features, bugs, spikes)
+                    3. USE SDK for tracking - all work must be tracked in .htmlgraph/
+                    4. RESPECT dependencies - check blockers before starting
+
+                    Key Rules:
+                    - Implementation work → delegate to general-purpose subagent
+                    - Research/exploration → delegate to explorer subagent
+                    - Testing/validation → delegate to test-runner subagent
+                    - Complex analysis → delegate to appropriate specialist
+
+                    Always use:
+                        from htmlgraph import SDK
+                        sdk = SDK(agent='orchestrator')
+
+                    See CLAUDE.md for complete orchestrator directives.
+                    """
+                )
+
+            if args.quiet or args.format == "json":
+                # Non-interactive: directly launch Claude with system prompt
+                cmd = ["claude", "--append-system-prompt", system_prompt]
+            else:
+                # Interactive: show summary first
+                print("=" * 60)
+                print("🤖 HtmlGraph Orchestrator Mode")
+                print("=" * 60)
+                print("\nStarting Claude Code with orchestrator system prompt...")
+                print("Key directives:")
+                print("  ✓ Delegate implementation to subagents")
+                print("  ✓ Create work items before delegating")
+                print("  ✓ Track all work in .htmlgraph/")
+                print("  ✓ Respect dependency chains")
+                print()
+
+                cmd = ["claude", "--append-system-prompt", system_prompt]
+
+            try:
+                subprocess.run(cmd, check=False)
+            except FileNotFoundError:
+                print("Error: 'claude' command not found.", file=sys.stderr)
+                print(
+                    "Please install Claude Code CLI: https://code.claude.com",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+        elif args.continue_session:
+            # Resume last Claude Code session
+            if args.quiet or args.format == "json":
+                cmd = ["claude", "--resume"]
+            else:
+                print("Resuming last Claude Code session...")
+                cmd = ["claude", "--resume"]
+
+            try:
+                subprocess.run(cmd, check=False)
+            except FileNotFoundError:
+                print("Error: 'claude' command not found.", file=sys.stderr)
+                print(
+                    "Please install Claude Code CLI: https://code.claude.com",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+        else:
+            # Default: start normal Claude Code session
+            try:
+                subprocess.run(["claude"], check=False)
+            except FileNotFoundError:
+                print("Error: 'claude' command not found.", file=sys.stderr)
+                print(
+                    "Please install Claude Code CLI: https://code.claude.com",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+    except Exception as e:
+        print(f"Error: Failed to start Claude Code: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(
         description="HtmlGraph - HTML is All You Need",
@@ -4917,6 +5090,24 @@ For more help: https://github.com/Shakes-tzd/htmlgraph
         help="Install the Gemini CLI extension from the bundled package",
     )
 
+    # claude - Start Claude Code with orchestrator support
+    claude_parser = subparsers.add_parser(
+        "claude", help="Start Claude Code with HtmlGraph integration"
+    )
+    claude_group = claude_parser.add_mutually_exclusive_group()
+    claude_group.add_argument(
+        "--init",
+        action="store_true",
+        help="Start with orchestrator system prompt (recommended)",
+    )
+    claude_group.add_argument(
+        "--continue",
+        dest="continue_session",
+        action="store_true",
+        help="Resume last Claude Code session",
+    )
+    claude_parser.set_defaults(func=cmd_claude)
+
     args = parser.parse_args()
 
     if args.command == "serve":
@@ -5154,6 +5345,8 @@ For more help: https://github.com/Shakes-tzd/htmlgraph
             sys.exit(1)
     elif args.command == "install-gemini-extension":
         cmd_install_gemini_extension(args)
+    elif args.command == "claude":
+        cmd_claude(args)
     else:
         parser.print_help()
         sys.exit(1)

htmlgraph/collections/base.py

@@ -91,6 +91,48 @@ class BaseCollection(Generic[CollectionT]):
 
         return self._graph
 
+    def __getattribute__(self, name: str) -> Any:
+        """Override to provide helpful error messages for missing attributes."""
+        try:
+            return object.__getattribute__(self, name)
+        except AttributeError as e:
+            # Get available methods
+            available = [m for m in dir(self) if not m.startswith("_")]
+
+            # Common mistakes mapping
+            common_mistakes = {
+                "mark_complete": "mark_done",
+                "complete": "Use complete(node_id) for single item or mark_done([ids]) for batch",
+                "finish": "mark_done",
+                "end": "mark_done",
+                "update_status": "edit() context manager or batch_update()",
+                "mark_as_done": "mark_done",
+                "set_done": "mark_done",
+                "complete_all": "mark_done",
+            }
+
+            suggestions = []
+            if name in common_mistakes:
+                suggestions.append(f"Did you mean: {common_mistakes[name]}")
+
+            # Find similar method names
+            similar = [
+                m
+                for m in available
+                if name.lower() in m.lower() or m.lower() in name.lower()
+            ]
+            if similar:
+                suggestions.append(f"Similar methods: {', '.join(similar[:5])}")
+
+            # Build helpful error message
+            error_msg = f"'{type(self).__name__}' has no attribute '{name}'."
+            if suggestions:
+                error_msg += "\n\n" + "\n".join(suggestions)
+            error_msg += f"\n\nAvailable methods: {', '.join(available[:15])}"
+            error_msg += "\n\nTip: Use sdk.help() to see all available operations."
+
+            raise AttributeError(error_msg) from e
+
     def __dir__(self) -> list[str]:
         """Return attributes with most useful ones first for discoverability."""
         priority = [
@@ -418,7 +460,7 @@ class BaseCollection(Generic[CollectionT]):
 
         return count
 
-    def mark_done(self, node_ids: list[str]) -> int:
+    def mark_done(self, node_ids: list[str]) -> dict[str, Any]:
         """
         Batch mark nodes as done.
 
@@ -426,12 +468,34 @@ class BaseCollection(Generic[CollectionT]):
             node_ids: List of node IDs to mark as done
 
         Returns:
-            Number of nodes updated
+            Dict with 'success_count', 'failed_ids', and 'warnings'
 
         Example:
-            >>> sdk.features.mark_done(["feat-001", "feat-002"])
+            >>> result = sdk.features.mark_done(["feat-001", "feat-002"])
+            >>> print(f"Completed {result['success_count']} of {len(node_ids)}")
+            >>> if result['failed_ids']:
+            ...     print(f"Failed: {result['failed_ids']}")
         """
-        return self.batch_update(node_ids, {"status": "done"})
+        graph = self._ensure_graph()
+        results: dict[str, Any] = {"success_count": 0, "failed_ids": [], "warnings": []}
+
+        for node_id in node_ids:
+            try:
+                node = graph.get(node_id)
+                if not node:
+                    results["failed_ids"].append(node_id)
+                    results["warnings"].append(f"Node {node_id} not found")
+                    continue
+
+                node.status = "done"
+                node.updated = datetime.now()
+                graph.update(node)
+                results["success_count"] += 1
+            except Exception as e:
+                results["failed_ids"].append(node_id)
+                results["warnings"].append(f"Failed to mark {node_id}: {str(e)}")
+
+        return results
 
     def assign(self, node_ids: list[str], agent: str) -> int:
         """

htmlgraph/git_events.py

@@ -168,9 +168,19 @@ def parse_feature_refs(message: str) -> list[str]:
     Parse feature IDs from commit message.
 
     Looks for patterns like:
-    - Implements: feature-xyz
+    - Implements: feat-xyz
     - Fixes: bug-abc
-    - feature-xyz
+    - [feat-123abc]
+    - feat-xyz
+
+    Supports HtmlGraph ID formats:
+    - feat-XXXXXXXX (features)
+    - feature-XXXXXXXX (legacy features)
+    - bug-XXXXXXXX (bugs)
+    - spk-XXXXXXXX (spikes)
+    - spike-XXXXXXXX (legacy spikes)
+    - chr-XXXXXXXX (chores)
+    - trk-XXXXXXXX (tracks)
 
     Args:
         message: Commit message
@@ -180,14 +190,21 @@ def parse_feature_refs(message: str) -> list[str]:
     """
     features = []
 
-    # Pattern: Implements: feature-xyz
-    pattern1 = r"(?:Implements|Fixes|Closes|Refs):\s*(feature-[\w-]+|bug-[\w-]+)"
+    # All HtmlGraph ID prefixes (current + legacy)
+    id_prefixes = r"(?:feat|feature|bug|spk|spike|chr|chore|trk|track|todo)"
+
+    # Pattern 1: Explicit tags (Implements: feat-xyz)
+    pattern1 = rf"(?:Implements|Fixes|Closes|Refs):\s*({id_prefixes}-[\w-]+)"
     features.extend(re.findall(pattern1, message, re.IGNORECASE))
 
-    # Pattern: feature-xyz (anywhere in message)
-    pattern2 = r"\b(feature-[\w-]+|bug-[\w-]+)\b"
+    # Pattern 2: Square brackets [feat-xyz] (common in commit messages)
+    pattern2 = rf"\[({id_prefixes}-[\w-]+)\]"
     features.extend(re.findall(pattern2, message, re.IGNORECASE))
 
+    # Pattern 3: Anywhere in message as word boundary
+    pattern3 = rf"\b({id_prefixes}-[\w-]+)\b"
+    features.extend(re.findall(pattern3, message, re.IGNORECASE))
+
     # Remove duplicates while preserving order
     seen = set()
     unique_features = []
@@ -288,7 +305,44 @@ def _determine_context(graph_dir: Path, commit_message: str | None = None) -> di
         if f and f not in all_features:
             all_features.append(f)
 
-    session = get_active_session(graph_dir)
+    # Try to find the right session based on feature IDs in commit message
+    # This handles multi-agent scenarios where multiple sessions are active
+    session = None
+    if message_features:
+        # If commit mentions specific features, find the session working on them
+        manager = _get_session_manager(graph_dir)
+        if manager:
+            try:
+                # Try to find a session that has any of the message features as active
+                for feature_id in message_features:
+                    # Get the feature to check which agent is working on it
+                    try:
+                        # Try features graph first
+                        feature = manager.features_graph.get(feature_id)
+                        if not feature:
+                            # Try bugs graph
+                            feature = manager.bugs_graph.get(feature_id)
+
+                        if (
+                            feature
+                            and hasattr(feature, "agent_assigned")
+                            and feature.agent_assigned
+                        ):
+                            # Find active session for this agent
+                            session = manager.get_active_session(
+                                agent=feature.agent_assigned
+                            )
+                            if session:
+                                break
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+
+    # Fallback to any active session if we couldn't match by feature
+    if not session:
+        session = get_active_session(graph_dir)
+
     if session:
         return {
             "session_id": session.id,