htmlgraph 0.23.3__tar.gz → 0.23.5__tar.gz

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.23.3
+Version: 0.23.5
 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
@@ -259,6 +259,7 @@ MIT
 ## Links
 
 - [GitHub](https://github.com/Shakes-tzd/htmlgraph)
+- [API Reference](docs/API_REFERENCE.md) - Complete SDK API documentation
 - [Documentation](docs/) - SDK guide, workflows, development principles
 - [Examples](examples/) - Real-world usage examples
 - [PyPI](https://pypi.org/project/htmlgraph/)

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/README.md

@@ -218,6 +218,7 @@ MIT
 ## Links
 
 - [GitHub](https://github.com/Shakes-tzd/htmlgraph)
+- [API Reference](docs/API_REFERENCE.md) - Complete SDK API documentation
 - [Documentation](docs/) - SDK guide, workflows, development principles
 - [Examples](examples/) - Real-world usage examples
 - [PyPI](https://pypi.org/project/htmlgraph/)

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/packages/gemini-extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlgraph",
-  "version": "0.23.3",
+  "version": "0.23.5",
   "description": "HtmlGraph session tracking and documentation for Gemini CLI. Ensures proper activity attribution, feature awareness, and continuous work tracking.",
   "author": "Shakes",
   "license": "MIT",

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "htmlgraph"
-version = "0.23.3"
+version = "0.23.5"
 description = "HTML is All You Need - Graph database on web standards"
 authors = [{name = "Shakes", email = "shakestzd@gmail.com"}]
 readme = "README.md"

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/src/python/htmlgraph/__init__.py

@@ -84,7 +84,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.23.3"
+__version__ = "0.23.5"
 __all__ = [
     # Exceptions
     "HtmlGraphError",

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/src/python/htmlgraph/agent_detection.py

@@ -20,8 +20,7 @@ def detect_agent_name() -> str:
         1. HTMLGRAPH_AGENT environment variable (explicit override)
         2. Claude Code detection (CLAUDE_CODE_VERSION, parent process)
         3. Gemini detection (GEMINI environment markers)
-        4. OpenCode detection (OPENCODE environment markers)
-        5. Fall back to "cli"
+        4. Fall back to "cli"
     """
     # 1. Explicit override
     explicit = os.environ.get("HTMLGRAPH_AGENT")
@@ -36,11 +35,7 @@ def detect_agent_name() -> str:
     if _is_gemini():
         return "gemini"
 
-    # 4. OpenCode detection
-    if _is_opencode():
-        return "opencode"
-
-    # 5. Default to CLI
+    # 4. Default to CLI
     return "cli"
 
 
@@ -93,39 +88,6 @@ def _is_gemini() -> bool:
     return False
 
 
-def _is_opencode() -> bool:
-    """Check if running in OpenCode environment."""
-    # Check for OpenCode-specific environment variables
-    if os.environ.get("OPENCODE_VERSION"):
-        return True
-
-    if os.environ.get("OPENCODE_API_KEY"):
-        return True
-
-    if os.environ.get("OPENCODE_SESSION_ID"):
-        return True
-
-    # Check for opencode in command line args
-    if any("opencode" in arg.lower() for arg in sys.argv):
-        return True
-
-    # Check for OpenCode configuration
-    try:
-        # Look for OpenCode config in common locations
-        opencode_config = Path.home() / ".opencode"
-        if opencode_config.exists():
-            return True
-
-        # Check project-level OpenCode config
-        project_config = Path.cwd() / ".opencode"
-        if project_config.exists():
-            return True
-    except Exception:
-        pass
-
-    return False
-
-
 def get_agent_display_name(agent: str) -> str:
     """
     Get a human-friendly display name for an agent.
@@ -140,7 +102,6 @@ def get_agent_display_name(agent: str) -> str:
         "claude": "Claude",
         "claude-code": "Claude",
         "gemini": "Gemini",
-        "opencode": "OpenCode",
         "cli": "CLI",
         "haiku": "Haiku",
         "opus": "Opus",

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/src/python/htmlgraph/cli.py

@@ -11,7 +11,8 @@ Usage:
 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
+    htmlgraph claude --continue         # Resume last Claude Code session (with plugin loaded)
+    htmlgraph claude --dev              # Start in development mode (load plugin from packages/)
 
 Session Management:
     htmlgraph session start [--id ID] [--agent AGENT]
@@ -170,7 +171,7 @@ def cmd_init(args: argparse.Namespace) -> None:
         generate_docs = True  # Always generate in non-interactive mode
 
     def init_progress() -> tuple[Any | None, Any | None]:
-        if args.quiet or getattr(args, "format", "text") != "text":
+        if getattr(args, "quiet", False) or getattr(args, "format", "text") != "text":
             return None, None
         try:
             from rich.console import Console
@@ -3589,6 +3590,19 @@ def cmd_claude(args: argparse.Namespace) -> None:
     """Start Claude Code with orchestrator prompt."""
     import textwrap
 
+    # Load orchestration rules from plugin
+    rules_file = (
+        Path(__file__).parent.parent.parent.parent
+        / "packages"
+        / "claude-plugin"
+        / "rules"
+        / "orchestration.md"
+    )
+
+    orchestration_rules = ""
+    if rules_file.exists():
+        orchestration_rules = rules_file.read_text(encoding="utf-8")
+
     try:
         if args.init:
             # Load optimized orchestrator system prompt
@@ -3622,9 +3636,14 @@ def cmd_claude(args: argparse.Namespace) -> None:
                     """
                 )
 
+            # Combine fallback prompt with orchestration rules
+            combined_prompt = system_prompt
+            if orchestration_rules:
+                combined_prompt = f"{system_prompt}\n\n---\n\n{orchestration_rules}"
+
             if args.quiet or args.format == "json":
                 # Non-interactive: directly launch Claude with system prompt
-                cmd = ["claude", "--append-system-prompt", system_prompt]
+                cmd = ["claude", "--append-system-prompt", combined_prompt]
             else:
                 # Interactive: show summary first
                 print("=" * 60)
@@ -3632,13 +3651,13 @@ def cmd_claude(args: argparse.Namespace) -> None:
                 print("=" * 60)
                 print("\nStarting Claude Code with orchestrator system prompt...")
                 print("Key directives:")
-                print("  ✓ Delegate implementation to subagents")
+                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("  ✓ Respect dependency chains")
                 print()
 
-                cmd = ["claude", "--append-system-prompt", system_prompt]
+                cmd = ["claude", "--append-system-prompt", combined_prompt]
 
             try:
                 subprocess.run(cmd, check=False)
@@ -3652,12 +3671,78 @@ def cmd_claude(args: argparse.Namespace) -> None:
 
         elif args.continue_session:
             # Resume last Claude Code session
+            # Find plugin directory relative to project root
+            plugin_dir = (
+                Path(__file__).parent.parent.parent.parent
+                / "packages"
+                / "claude-plugin"
+                / ".claude-plugin"
+            )
+
             if args.quiet or args.format == "json":
                 cmd = ["claude", "--resume"]
             else:
                 print("Resuming last Claude Code session...")
                 cmd = ["claude", "--resume"]
 
+            # Add orchestration rules if available
+            if orchestration_rules:
+                cmd.extend(["--append-system-prompt", orchestration_rules])
+                if not (args.quiet or args.format == "json"):
+                    print("  ✓ Multi-AI delegation rules injected")
+
+            # Add plugin directory if it exists
+            if plugin_dir.exists():
+                cmd.extend(["--plugin-dir", str(plugin_dir)])
+                if not (args.quiet or args.format == "json"):
+                    print(f"  ✓ Loading plugin from: {plugin_dir}")
+
+            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.dev:
+            # Development mode: load plugin from local directory
+            plugin_dir = (
+                Path(__file__).parent.parent.parent.parent
+                / "packages"
+                / "claude-plugin"
+                / ".claude-plugin"
+            )
+
+            if not plugin_dir.exists():
+                print(
+                    f"Error: Plugin directory not found: {plugin_dir}", file=sys.stderr
+                )
+                print(
+                    "Expected location: packages/claude-plugin/.claude-plugin",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+            if args.quiet or args.format == "json":
+                cmd = ["claude", "--plugin-dir", str(plugin_dir)]
+            else:
+                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("  ✓ Multi-AI delegation rules will be injected")
+                print("  ✓ Changes to plugin files will take effect after restart")
+                print()
+                cmd = ["claude", "--plugin-dir", str(plugin_dir)]
+
+            # Add orchestration rules if available
+            if orchestration_rules:
+                cmd.extend(["--append-system-prompt", orchestration_rules])
+
             try:
                 subprocess.run(cmd, check=False)
             except FileNotFoundError:
@@ -3670,8 +3755,16 @@ def cmd_claude(args: argparse.Namespace) -> None:
 
         else:
             # Default: start normal Claude Code session
+            cmd = ["claude"]
+
+            # Add orchestration rules if available
+            if orchestration_rules:
+                cmd.extend(["--append-system-prompt", orchestration_rules])
+                if not (args.quiet or args.format == "json"):
+                    print("Starting Claude Code with multi-AI delegation rules...")
+
             try:
-                subprocess.run(["claude"], check=False)
+                subprocess.run(cmd, check=False)
             except FileNotFoundError:
                 print("Error: 'claude' command not found.", file=sys.stderr)
                 print(
@@ -5106,6 +5199,11 @@ For more help: https://github.com/Shakes-tzd/htmlgraph
         action="store_true",
         help="Resume last Claude Code session",
     )
+    claude_group.add_argument(
+        "--dev",
+        action="store_true",
+        help="Start in development mode with plugin loaded from packages/claude-plugin",
+    )
     claude_parser.set_defaults(func=cmd_claude)
 
     args = parser.parse_args()

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/src/python/htmlgraph/collections/base.py

@@ -71,7 +71,19 @@ class BaseCollection(Generic[CollectionT]):
         self._graph: HtmlGraph | None = None  # Lazy-loaded
 
     def _ensure_graph(self) -> HtmlGraph:
-        """Get the graph for this collection, using SDK's shared instances where available."""
+        """
+        Get or initialize the graph for this collection.
+
+        Uses SDK's shared graph instances where available to avoid creating
+        multiple graph objects for the same collection. Creates a new instance
+        for unrecognized collections.
+
+        Returns:
+            HtmlGraph instance for this collection
+
+        Note:
+            This method is lazy - the graph is only loaded on first access.
+        """
         if self._graph is None:
             # Use SDK's shared graph instances to avoid multiple graph objects
             if self._collection_name == "features" and hasattr(self._sdk, "_graph"):
@@ -92,7 +104,21 @@ class BaseCollection(Generic[CollectionT]):
         return self._graph
 
     def __getattribute__(self, name: str) -> Any:
-        """Override to provide helpful error messages for missing attributes."""
+        """
+        Override attribute access to provide helpful error messages.
+
+        When an attribute doesn't exist, provides suggestions for common
+        mistakes and similar method names to improve discoverability.
+
+        Args:
+            name: Attribute name being accessed
+
+        Returns:
+            The requested attribute
+
+        Raises:
+            AttributeError: With helpful suggestions if attribute not found
+        """
         try:
             return object.__getattribute__(self, name)
         except AttributeError as e:
@@ -134,7 +160,15 @@ class BaseCollection(Generic[CollectionT]):
             raise AttributeError(error_msg) from e
 
     def __dir__(self) -> list[str]:
-        """Return attributes with most useful ones first for discoverability."""
+        """
+        Return attributes with most useful ones first.
+
+        Orders attributes to show commonly-used methods first in auto-complete
+        and help() output, improving discoverability for new users.
+
+        Returns:
+            List of attribute names, ordered by priority then alphabetically
+        """
         priority = [
             # Creation and retrieval
             "create",
@@ -518,13 +552,15 @@ class BaseCollection(Generic[CollectionT]):
         """
         Start working on a node (feature/bug/etc).
 
-        Delegates to SessionManager to:
+        Delegates to SessionManager if available for smart tracking:
         1. Check WIP limits
         2. Ensure not claimed by others
         3. Auto-claim for agent
         4. Link to active session
         5. Log 'FeatureStart' event
 
+        Falls back to simple status update if SessionManager not available.
+
         Args:
             node_id: Node ID to start
             agent: Agent ID (defaults to SDK agent)
@@ -534,6 +570,10 @@ class BaseCollection(Generic[CollectionT]):
 
         Raises:
             NodeNotFoundError: If node not found
+
+        Example:
+            >>> sdk.features.start('feat-abc123')
+            >>> sdk.features.start('feat-xyz', agent='claude')
         """
         agent = agent or self._sdk.agent
 
@@ -566,14 +606,17 @@ class BaseCollection(Generic[CollectionT]):
         transcript_id: str | None = None,
     ) -> Node | None:
         """
-        Complete a node.
+        Mark a node as complete.
 
-        Delegates to SessionManager to:
-        1. Update status
+        Delegates to SessionManager if available for event logging and
+        transcript linking:
+        1. Update status to 'done'
         2. Log 'FeatureComplete' event
         3. Release claim (optional behavior)
         4. Link transcript if provided (for parallel agent tracking)
 
+        Falls back to simple status update if SessionManager not available.
+
         Args:
             node_id: Node ID to complete
             agent: Agent ID (defaults to SDK agent)
@@ -585,6 +628,10 @@ class BaseCollection(Generic[CollectionT]):
 
         Raises:
             NodeNotFoundError: If node not found
+
+        Example:
+            >>> sdk.features.complete('feat-abc123')
+            >>> sdk.features.complete('feat-xyz', agent='claude', transcript_id='trans-123')
         """
         agent = agent or self._sdk.agent
 
@@ -615,11 +662,13 @@ class BaseCollection(Generic[CollectionT]):
         """
         Claim a node for an agent.
 
-        Delegates to SessionManager to:
+        Delegates to SessionManager if available for ownership tracking:
         1. Check ownership rules
         2. Update assignment
         3. Log 'FeatureClaim' event
 
+        Falls back to simple assignment if SessionManager not available.
+
         Args:
             node_id: Node ID to claim
             agent: Agent ID (defaults to SDK agent)
@@ -631,6 +680,10 @@ class BaseCollection(Generic[CollectionT]):
             ValueError: If agent not provided and SDK has no agent
             NodeNotFoundError: If node not found
             ClaimConflictError: If node already claimed by different agent
+
+        Example:
+            >>> sdk.features.claim('feat-abc123')
+            >>> sdk.features.claim('feat-xyz', agent='claude')
         """
         agent = agent or self._sdk.agent
         if not agent:
@@ -665,11 +718,13 @@ class BaseCollection(Generic[CollectionT]):
         """
         Release a claimed node.
 
-        Delegates to SessionManager to:
+        Delegates to SessionManager if available for ownership tracking:
         1. Verify ownership
         2. Clear assignment
         3. Log 'FeatureRelease' event
 
+        Falls back to simple assignment clearing if SessionManager not available.
+
         Args:
             node_id: Node ID to release
             agent: Agent ID (defaults to SDK agent)
@@ -679,6 +734,10 @@ class BaseCollection(Generic[CollectionT]):
 
         Raises:
             NodeNotFoundError: If node not found
+
+        Example:
+            >>> sdk.features.release('feat-abc123')
+            >>> sdk.features.release('feat-xyz', agent='claude')
         """
         # SessionManager.release_feature requires an agent to verify ownership
         agent = agent or self._sdk.agent

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/src/python/htmlgraph/converter.py

@@ -395,7 +395,8 @@ def html_to_session(filepath: Path | str) -> Session:
     parser = HtmlParser.from_file(filepath)
 
     # Get article element with session data
-    article = parser.query_one("article[data-type='session']")
+    article_results = parser.query("article[data-type='session']")
+    article = article_results[0] if article_results else None
     if not article:
         raise ValueError(f"No session article found in: {filepath}")
 
@@ -465,7 +466,8 @@ def html_to_session(filepath: Path | str) -> Session:
         data["transcript_git_branch"] = transcript_branch
 
     # Parse title
-    title_el = parser.query_one("h1")
+    title_el_results = parser.query("h1")
+    title_el = title_el_results[0] if title_el_results else None
     if title_el:
         data["title"] = title_el.to_text().strip()
 
@@ -482,24 +484,28 @@ def html_to_session(filepath: Path | str) -> Session:
     data["worked_on"] = worked_on
 
     # Parse continued_from edge
-    continued_link = parser.query_one(
+    continued_link_results = parser.query(
         "nav[data-graph-edges] section[data-edge-type='continued-from'] a"
     )
+    continued_link = continued_link_results[0] if continued_link_results else None
     if continued_link:
         href = continued_link.attrs.get("href") or ""
         data["continued_from"] = href.replace(".html", "")
 
     # Parse handoff context
-    handoff_section = parser.query_one("section[data-handoff]")
+    handoff_section_results = parser.query("section[data-handoff]")
+    handoff_section = handoff_section_results[0] if handoff_section_results else None
     if handoff_section:
-        notes_el = parser.query_one("section[data-handoff] [data-handoff-notes]")
+        notes_el_results = parser.query("section[data-handoff] [data-handoff-notes]")
+        notes_el = notes_el_results[0] if notes_el_results else None
         if notes_el:
             notes_text = notes_el.to_text().strip()
             if notes_text.lower().startswith("notes:"):
                 notes_text = notes_text.split(":", 1)[1].strip()
             data["handoff_notes"] = notes_text
 
-        next_el = parser.query_one("section[data-handoff] [data-recommended-next]")
+        next_el_results = parser.query("section[data-handoff] [data-recommended-next]")
+        next_el = next_el_results[0] if next_el_results else None
         if next_el:
             next_text = next_el.to_text().strip()
             if next_text.lower().startswith("recommended next:"):

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/src/python/htmlgraph/models.py

@@ -317,6 +317,24 @@ class Node(BaseModel):
             "session_ids": self.context_sessions,
         }
 
+    def to_dict(self) -> dict:
+        """
+        Convert Node to dictionary format.
+
+        This is a convenience alias for Pydantic's model_dump() method,
+        providing a more discoverable API for serialization.
+
+        Returns:
+            dict: Dictionary representation of the Node with all fields
+
+        Example:
+            >>> feature = sdk.features.create("My Feature").save()
+            >>> data = feature.to_dict()
+            >>> print(data['title'])
+            'My Feature'
+        """
+        return self.model_dump()
+
     def to_html(self, stylesheet_path: str = "../styles.css") -> str:
         """
         Convert node to full HTML document.

{htmlgraph-0.23.3 → htmlgraph-0.23.5}/src/python/htmlgraph/orchestration/headless_spawner.py

@@ -65,7 +65,6 @@ class HeadlessSpawner:
         output_format: str = "json",
         model: str | None = None,
         include_directories: list[str] | None = None,
-        color: str = "auto",
         timeout: int = 120,
     ) -> AIResult:
         """
@@ -76,7 +75,6 @@ class HeadlessSpawner:
             output_format: "json" or "stream-json"
             model: Model selection (e.g., "gemini-2.0-flash"). Default: None (uses default)
             include_directories: List of directories to include for context. Default: None
-            color: Color output control ("auto", "on", "off"). Default: "auto"
             timeout: Max seconds to wait
 
         Returns:
@@ -95,8 +93,8 @@ class HeadlessSpawner:
                 for directory in include_directories:
                     cmd.extend(["--include-directories", directory])
 
-            # Add color option
-            cmd.extend(["--color", color])
+            # CRITICAL: Add --yolo for headless mode (auto-approve all tools)
+            cmd.append("--yolo")
 
             # Execute with timeout and stderr redirection
             # Note: Cannot use capture_output with stderr parameter
@@ -180,13 +178,11 @@ class HeadlessSpawner:
     def spawn_codex(
         self,
         prompt: str,
-        approval: str = "never",
         output_json: bool = True,
         model: str | None = None,
         sandbox: str | None = None,
-        full_auto: bool = False,
+        full_auto: bool = True,
         images: list[str] | None = None,
-        color: str = "auto",
         output_last_message: str | None = None,
         output_schema: str | None = None,
         skip_git_check: bool = False,
@@ -200,13 +196,11 @@ class HeadlessSpawner:
 
         Args:
             prompt: Task description for Codex
-            approval: Approval mode ("never", "always")
             output_json: Use --json flag for JSONL output
             model: Model selection (e.g., "gpt-4-turbo"). Default: None
             sandbox: Sandbox mode ("read-only", "workspace-write", "danger-full-access"). Default: None
-            full_auto: Enable full auto mode (--full-auto). Default: False
+            full_auto: Enable full auto mode (--full-auto). Default: True (required for headless)
             images: List of image paths (--image). Default: None
-            color: Color output control ("auto", "on", "off"). Default: "auto"
             output_last_message: Write last message to file (--output-last-message). Default: None
             output_schema: JSON schema for validation (--output-schema). Default: None
             skip_git_check: Skip git repo check (--skip-git-repo-check). Default: False
@@ -240,9 +234,6 @@ class HeadlessSpawner:
             for image in images:
                 cmd.extend(["--image", image])
 
-        # Add color option
-        cmd.extend(["--color", color])
-
         # Add output last message file if specified
         if output_last_message:
             cmd.extend(["--output-last-message", output_last_message])
@@ -267,7 +258,8 @@ class HeadlessSpawner:
         if bypass_approvals:
             cmd.append("--dangerously-bypass-approvals-and-sandbox")
 
-        cmd.extend(["--approval", approval, prompt])
+        # Add prompt as final argument
+        cmd.append(prompt)
 
         try:
             result = subprocess.run(