htmlgraph 0.26.5__py3-none-any.whl → 0.26.7__py3-none-any.whl

htmlgraph/operations/initialization.py.backup

@@ -0,0 +1,228 @@
+"""HtmlGraph initialization operations.
+
+This module provides functions for initializing the .htmlgraph directory structure,
+creating necessary files, and optionally installing Git hooks.
+
+The initialization process includes:
+1. Directory structure creation (.htmlgraph with subdirectories)
+2. Database initialization (htmlgraph.db)
+3. Index creation (index.sqlite)
+4. Configuration files
+5. Optional Git hooks installation
+
+Extracted from monolithic cmd_init() implementation for better maintainability.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.cli.models import InitConfig, InitResult, ValidationResult
+
+
+# Default collections to create
+DEFAULT_COLLECTIONS = [
+    "features",
+    "bugs",
+    "chores",
+    "spikes",
+    "epics",
+    "phases",
+    "tracks",
+    "sessions",
+    "insights",
+    "metrics",
+    "agents",
+    "cigs",
+]
+
+# Additional directories
+ADDITIONAL_DIRECTORIES = [
+    "events",
+    "logs",
+    "archive-index",
+    "archives",
+]
+
+
+def initialize_htmlgraph(config: InitConfig) -> InitResult:
+    """Initialize .htmlgraph directory structure.
+
+    Creates the standard HtmlGraph directory structure:
+    - .htmlgraph/
+      - features/
+      - sessions/
+      - spikes/
+      - bugs/
+      - tracks/
+      - events/
+      - logs/
+
+    Args:
+        config: Initialization configuration
+
+    Returns:
+        InitResult with success status and details
+    """
+    try:
+        # Resolve directory path
+        base_dir = Path(config.dir).resolve()
+        htmlgraph_dir = base_dir / ".htmlgraph"
+
+        created_dirs: list[str] = []
+        updated_files: list[str] = []
+
+        # Create main directory
+        if not htmlgraph_dir.exists():
+            htmlgraph_dir.mkdir(parents=True, exist_ok=True)
+            created_dirs.append(str(htmlgraph_dir))
+
+        # Create standard subdirectories
+        subdirs = [
+            "features",
+            "sessions",
+            "spikes",
+            "bugs",
+            "tracks",
+            "events",
+            "logs",
+            "logs/errors",
+        ]
+
+        for subdir in subdirs:
+            subdir_path = htmlgraph_dir / subdir
+            if not subdir_path.exists():
+                subdir_path.mkdir(parents=True, exist_ok=True)
+                created_dirs.append(str(subdir_path))
+
+        # Create .gitkeep in events directory (unless disabled)
+        if not config.no_events_keep:
+            events_dir = htmlgraph_dir / "events"
+            gitkeep_file = events_dir / ".gitkeep"
+            if not gitkeep_file.exists():
+                gitkeep_file.touch()
+                updated_files.append(str(gitkeep_file))
+
+        # Update .gitignore (unless disabled)
+        if not config.no_update_gitignore:
+            gitignore_path = base_dir / ".gitignore"
+            gitignore_entries = [
+                "# HtmlGraph cache files",
+                ".htmlgraph/index.sqlite",
+                ".htmlgraph/htmlgraph.db",
+                ".htmlgraph/sessions/*.jsonl",
+                ".htmlgraph/events/*.jsonl",
+                ".htmlgraph/parent-activity.json",
+            ]
+
+            # Read existing .gitignore
+            existing_entries: set[str] = set()
+            if gitignore_path.exists():
+                existing_entries = set(
+                    line.strip() for line in gitignore_path.read_text().splitlines()
+                )
+
+            # Add missing entries
+            new_entries = [
+                entry for entry in gitignore_entries if entry not in existing_entries
+            ]
+
+            if new_entries:
+                mode = "a" if gitignore_path.exists() else "w"
+                with gitignore_path.open(mode) as f:
+                    if mode == "a":
+                        f.write("\n")  # Add newline before appending
+                    f.write("\n".join(new_entries) + "\n")
+                updated_files.append(str(gitignore_path))
+
+        # Initialize analytics index (unless disabled)
+        if not config.no_index:
+            from htmlgraph.analytics_index import AnalyticsIndex
+
+            index_path = htmlgraph_dir / "index.sqlite"
+            if not index_path.exists():
+                # Create empty index (will be populated on first use)
+                index = AnalyticsIndex(str(index_path))
+                index.ensure_schema()
+                created_dirs.append(str(index_path))
+
+        # Install Git hooks (if requested)
+        if config.install_hooks:
+            from htmlgraph.operations.hooks import install_hooks
+
+            try:
+                hooks_result = install_hooks(project_dir=base_dir, use_copy=False)
+                if hooks_result.installed:
+                    updated_files.extend(hooks_result.installed)
+                if hooks_result.warnings:
+                    for warning in hooks_result.warnings:
+                        print(f"Warning: {warning}", file=sys.stderr)
+            except Exception as e:
+                # Non-fatal: hooks installation failed but init succeeded
+                print(f"Warning: Failed to install hooks: {e}", file=sys.stderr)
+
+        # Interactive setup wizard (if requested)
+        if config.interactive:
+            _run_interactive_setup(htmlgraph_dir)
+
+        # Build success message
+        message_parts = []
+        if created_dirs:
+            message_parts.append(f"Created {len(created_dirs)} directories")
+        if updated_files:
+            message_parts.append(f"Updated {len(updated_files)} files")
+
+        message = ", ".join(message_parts) if message_parts else "Already initialized"
+
+        return InitResult(
+            success=True,
+            directory=htmlgraph_dir,
+            message=message,
+            created_dirs=created_dirs,
+            updated_files=updated_files,
+        )
+
+    except Exception as e:
+        return InitResult(
+            success=False,
+            directory=Path(config.dir).resolve() / ".htmlgraph",
+            error=f"Initialization failed: {e}",
+        )
+
+
+def _run_interactive_setup(htmlgraph_dir: Path) -> None:
+    """Run interactive setup wizard.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+    """
+    print("\n=== HtmlGraph Interactive Setup ===\n")
+
+    # Ask about project name
+    project_name = input("Project name (optional, press Enter to skip): ").strip()
+
+    # Ask about default agent
+    default_agent = input("Default agent name (default: claude): ").strip()
+    if not default_agent:
+        default_agent = "claude"
+
+    # Create config file
+    config_file = htmlgraph_dir / "config.json"
+    if not config_file.exists():
+        import json
+
+        config_data = {}
+        if project_name:
+            config_data["project_name"] = project_name
+        config_data["default_agent"] = default_agent
+
+        config_file.write_text(json.dumps(config_data, indent=2) + "\n")
+        print(f"\n✓ Created config file: {config_file}")
+
+    print("\n✓ Interactive setup complete!\n")

htmlgraph/orchestration/__init__.py

@@ -9,6 +9,15 @@ from .model_selection import (
     get_fallback_chain,
     select_model,
 )
+
+# Export modular spawners for advanced usage
+from .spawners import (
+    BaseSpawner,
+    ClaudeSpawner,
+    CodexSpawner,
+    CopilotSpawner,
+    GeminiSpawner,
+)
 from .task_coordination import (
     delegate_with_id,
     generate_task_id,
@@ -19,9 +28,15 @@ from .task_coordination import (
 )
 
 __all__ = [
-    # Headless AI spawning
+    # Headless AI spawning (unified interface)
     "HeadlessSpawner",
     "AIResult",
+    # Modular spawner implementations
+    "BaseSpawner",
+    "GeminiSpawner",
+    "CodexSpawner",
+    "CopilotSpawner",
+    "ClaudeSpawner",
     # Model selection
     "ModelSelection",
     "TaskType",

htmlgraph/orchestration/claude_launcher.py

@@ -0,0 +1,185 @@
+"""Claude Code launcher with multiple integration modes.
+
+Coordinates launching Claude Code with various HtmlGraph integration options.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from htmlgraph.orchestration.command_builder import ClaudeCommandBuilder
+from htmlgraph.orchestration.plugin_manager import PluginManager
+from htmlgraph.orchestration.prompts import get_orchestrator_prompt
+from htmlgraph.orchestration.subprocess_runner import SubprocessRunner
+
+
+class ClaudeLauncher:
+    """Launch Claude Code with various HtmlGraph integration modes.
+
+    Supports four launch scenarios:
+    1. --init: Orchestrator mode with plugin installation
+    2. --continue: Resume last session with orchestrator rules
+    3. --dev: Development mode with local plugin
+    4. default: Minimal orchestrator rules
+    """
+
+    def __init__(self, args: argparse.Namespace) -> None:
+        """Initialize launcher with parsed arguments.
+
+        Args:
+            args: Parsed command-line arguments
+        """
+        self.args = args
+        self.interactive = not (args.quiet or args.format == "json")
+
+    def launch(self) -> None:
+        """Main entry point - routes to appropriate scenario.
+
+        Raises:
+            SystemExit: On error during launch
+        """
+        try:
+            if self.args.init:
+                self._launch_orchestrator_mode()
+            elif self.args.continue_session:
+                self._launch_resume_mode()
+            elif self.args.dev:
+                self._launch_dev_mode()
+            else:
+                self._launch_default_mode()
+        except Exception as e:
+            print(f"Error: Failed to start Claude Code: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    def _launch_orchestrator_mode(self) -> None:
+        """Launch with orchestrator prompt (--init).
+
+        Installs plugin, loads orchestrator system prompt, and starts Claude Code
+        in orchestrator mode with multi-AI delegation rules.
+        """
+        # Install plugin
+        PluginManager.install_or_update(verbose=self.interactive)
+
+        # Load prompt
+        prompt = get_orchestrator_prompt(include_dev_mode=False)
+
+        # Show banner
+        if self.interactive:
+            self._print_orchestrator_banner()
+
+        # Build command
+        cmd = ClaudeCommandBuilder().with_system_prompt(prompt).build()
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _launch_resume_mode(self) -> None:
+        """Resume last session with orchestrator rules (--continue).
+
+        Installs plugin, loads plugin directory, and resumes the last Claude Code
+        session with orchestrator system prompt.
+        """
+        # Install plugin
+        PluginManager.install_or_update(verbose=self.interactive)
+
+        # Get plugin directory
+        plugin_dir = PluginManager.get_plugin_dir()
+
+        # Load prompt
+        prompt = get_orchestrator_prompt(include_dev_mode=False)
+
+        # Show status
+        if self.interactive:
+            print("Resuming last Claude Code session...")
+            print("  ✓ Multi-AI delegation rules injected")
+
+        # Build command
+        builder = ClaudeCommandBuilder().with_resume().with_system_prompt(prompt)
+
+        # Add plugin directory if exists
+        if plugin_dir.exists():
+            builder.with_plugin_dir(str(plugin_dir))
+            if self.interactive:
+                print(f"  ✓ Loading plugin from: {plugin_dir}")
+
+        cmd = builder.build()
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _launch_dev_mode(self) -> None:
+        """Launch with local plugin for development (--dev).
+
+        Loads plugin from local source directory for development/testing.
+        Changes to plugin files take effect after restart.
+        """
+        # Get and validate plugin directory
+        plugin_dir = PluginManager.get_plugin_dir()
+        PluginManager.validate_plugin_dir(plugin_dir)
+
+        # Load prompt with dev mode
+        prompt = get_orchestrator_prompt(include_dev_mode=True)
+
+        # Show banner
+        if self.interactive:
+            self._print_dev_mode_banner(plugin_dir)
+
+        # Build command
+        cmd = (
+            ClaudeCommandBuilder()
+            .with_plugin_dir(str(plugin_dir))
+            .with_system_prompt(prompt)
+            .build()
+        )
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _launch_default_mode(self) -> None:
+        """Launch with minimal orchestrator rules (default).
+
+        Starts Claude Code with basic multi-AI delegation rules but no plugin.
+        """
+        # Load prompt
+        prompt = get_orchestrator_prompt(include_dev_mode=False)
+
+        # Show status
+        if self.interactive:
+            print("Starting Claude Code with multi-AI delegation rules...")
+
+        # Build command
+        cmd = ClaudeCommandBuilder().with_system_prompt(prompt).build()
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _print_orchestrator_banner(self) -> None:
+        """Print orchestrator mode banner."""
+        print("=" * 60)
+        print("🤖 HtmlGraph Orchestrator Mode")
+        print("=" * 60)
+        print("\nStarting Claude Code with orchestrator system prompt...")
+        print("Key directives:")
+        print("  ✓ Delegate to Gemini (FREE), Codex, Copilot first")
+        print("  ✓ Use Task() only as fallback")
+        print("  ✓ Create work items before delegating")
+        print("  ✓ Track all work in .htmlgraph/")
+        print()
+
+    def _print_dev_mode_banner(self, plugin_dir: Path) -> None:
+        """Print development mode banner.
+
+        Args:
+            plugin_dir: Path to local plugin directory
+        """
+        print("=" * 60)
+        print("🔧 HtmlGraph Development Mode")
+        print("=" * 60)
+        print(f"\nLoading plugin from: {plugin_dir}")
+        print("  ✓ Skills, agents, and hooks will be loaded from local files")
+        print("  ✓ Orchestrator system prompt will be appended")
+        print("  ✓ Multi-AI delegation rules will be injected")
+        print("  ✓ Changes to plugin files will take effect after restart")
+        print()

htmlgraph/orchestration/command_builder.py

@@ -0,0 +1,71 @@
+"""Command builder for Claude Code CLI invocations.
+
+Provides fluent interface for constructing Claude CLI commands.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ClaudeCommandBuilder:
+    """Fluent builder for Claude Code CLI commands.
+
+    Example:
+        >>> builder = ClaudeCommandBuilder()
+        >>> cmd = builder.with_resume() \\
+        ...     .with_plugin_dir("/path/to/plugin") \\
+        ...     .with_system_prompt("System prompt text") \\
+        ...     .build()
+        >>> # Result: ["claude", "--resume", "--plugin-dir", "/path/to/plugin",
+        ...  #          "--append-system-prompt", "System prompt text"]
+    """
+
+    def __init__(self) -> None:
+        """Initialize with base command."""
+        self._cmd: list[str] = ["claude"]
+
+    def with_resume(self) -> ClaudeCommandBuilder:
+        """Add --resume flag to resume last session.
+
+        Returns:
+            Self for method chaining
+        """
+        self._cmd.append("--resume")
+        return self
+
+    def with_plugin_dir(self, plugin_dir: str | Path) -> ClaudeCommandBuilder:
+        """Add --plugin-dir flag.
+
+        Args:
+            plugin_dir: Path to plugin directory
+
+        Returns:
+            Self for method chaining
+        """
+        self._cmd.extend(["--plugin-dir", str(plugin_dir)])
+        return self
+
+    def with_system_prompt(self, prompt: str) -> ClaudeCommandBuilder:
+        """Add --append-system-prompt flag.
+
+        Args:
+            prompt: System prompt text to append
+
+        Returns:
+            Self for method chaining
+        """
+        if prompt:  # Only add if prompt is not empty
+            self._cmd.extend(["--append-system-prompt", prompt])
+        return self
+
+    def build(self) -> list[str]:
+        """Build the final command list.
+
+        Returns:
+            List of command arguments ready for subprocess.run()
+        """
+        return self._cmd