htmlgraph 0.21.0__py3-none-any.whl → 0.23.0__py3-none-any.whl

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/docs/__init__.py

@@ -0,0 +1,77 @@
+"""
+Documentation version tracking and migration system with template-based user customization.
+"""
+
+from pathlib import Path
+
+from htmlgraph import __version__
+from htmlgraph.docs.docs_version import (
+    DOC_VERSIONS,
+    DocVersion,
+    get_current_doc_version,
+    is_compatible,
+)
+from htmlgraph.docs.metadata import DocsMetadata
+from htmlgraph.docs.migrations import MIGRATIONS, MigrationScript, get_migration
+from htmlgraph.docs.template_engine import DocTemplateEngine
+from htmlgraph.docs.version_check import check_docs_version, upgrade_docs_interactive
+
+__all__ = [
+    "DOC_VERSIONS",
+    "DocVersion",
+    "get_current_doc_version",
+    "is_compatible",
+    "DocsMetadata",
+    "MigrationScript",
+    "MIGRATIONS",
+    "get_migration",
+    "check_docs_version",
+    "upgrade_docs_interactive",
+    "DocTemplateEngine",
+    "get_agents_md",
+    "sync_docs_to_file",
+]
+
+
+def get_agents_md(htmlgraph_dir: Path, platform: str = "claude") -> str:
+    """Get AGENTS.md content with user customizations merged.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        platform: Platform name (claude, gemini, etc.)
+
+    Returns:
+        Merged documentation content
+
+    Example:
+        >>> from pathlib import Path
+        >>> content = get_agents_md(Path(".htmlgraph"), "claude")
+    """
+    engine = DocTemplateEngine(htmlgraph_dir)
+    return engine.render_agents_md(__version__, platform)
+
+
+def sync_docs_to_file(
+    htmlgraph_dir: Path, output_file: Path, platform: str = "claude"
+) -> Path:
+    """Generate and write documentation to file.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        output_file: Path where documentation should be written
+        platform: Platform name (claude, gemini, etc.)
+
+    Returns:
+        Path to written file
+
+    Example:
+        >>> from pathlib import Path
+        >>> sync_docs_to_file(
+        ...     Path(".htmlgraph"),
+        ...     Path("AGENTS.md"),
+        ...     "claude"
+        ... )
+    """
+    content = get_agents_md(htmlgraph_dir, platform)
+    output_file.write_text(content)
+    return output_file

htmlgraph/docs/docs_version.py

@@ -0,0 +1,55 @@
+"""
+Documentation schema version management.
+
+This module defines version compatibility rules for HtmlGraph documentation files.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class DocVersion:
+    """Documentation schema version."""
+
+    version: int  # Schema version (1, 2, 3)
+    package_version: str  # Minimum package version (e.g., "0.20.0")
+    breaking_changes: list[str]
+    migration_required: bool = False
+
+
+# Version compatibility matrix
+DOC_VERSIONS = {
+    1: DocVersion(
+        version=1,
+        package_version="0.1.0",
+        breaking_changes=[],
+        migration_required=False,
+    ),
+    2: DocVersion(
+        version=2,
+        package_version="0.20.0",
+        breaking_changes=[
+            "AGENTS.md structure changed to use Jinja2 templates",
+            "Removed root-level CLAUDE.md/GEMINI.md (moved to .htmlgraph/docs/)",
+        ],
+        migration_required=True,
+    ),
+}
+
+
+def get_current_doc_version() -> int:
+    """Get current documentation schema version for this package."""
+    return 2  # Current version
+
+
+def is_compatible(user_version: int, package_version: int) -> bool:
+    """Check if user's doc version is compatible with package.
+
+    Args:
+        user_version: User's documentation schema version
+        package_version: Package's required documentation schema version
+
+    Returns:
+        True if compatible (supports N-1 versions)
+    """
+    return user_version >= package_version - 1  # Support N-1 versions

htmlgraph/docs/metadata.py

@@ -0,0 +1,93 @@
+"""
+Documentation metadata storage and management.
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class DocsMetadata(BaseModel):
+    """Metadata for project documentation."""
+
+    schema_version: int = 2
+    last_updated: datetime = Field(default_factory=datetime.now)
+    customizations: list[str] = []  # List of user-customized sections
+    base_version_on_last_update: str = "0.21.0"
+
+    @classmethod
+    def load(cls, htmlgraph_dir: Path) -> "DocsMetadata":
+        """Load metadata from .docs-metadata.json.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+
+        Returns:
+            DocsMetadata instance (default if file doesn't exist)
+        """
+        import json
+
+        metadata_file = htmlgraph_dir / ".docs-metadata.json"
+        if metadata_file.exists():
+            data = json.loads(metadata_file.read_text())
+            return cls(**data)
+        return cls()  # Default
+
+    def save(self, htmlgraph_dir: Path) -> None:
+        """Save metadata to .docs-metadata.json.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+        """
+        metadata_file = htmlgraph_dir / ".docs-metadata.json"
+        metadata_file.write_text(self.model_dump_json(indent=2))
+
+    @classmethod
+    def create_initial(
+        cls, htmlgraph_dir: Path, schema_version: int = 2
+    ) -> "DocsMetadata":
+        """Create initial metadata file.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            schema_version: Documentation schema version
+
+        Returns:
+            New DocsMetadata instance
+        """
+        from htmlgraph import __version__
+
+        metadata = cls(
+            schema_version=schema_version,
+            base_version_on_last_update=__version__,
+            customizations=[],
+        )
+        metadata.save(htmlgraph_dir)
+        return metadata
+
+    def add_customization(self, section_name: str) -> None:
+        """Mark a section as customized.
+
+        Args:
+            section_name: Name of the customized section
+        """
+        if section_name not in self.customizations:
+            self.customizations.append(section_name)
+
+    def remove_customization(self, section_name: str) -> None:
+        """Remove a customization marker.
+
+        Args:
+            section_name: Name of the section to unmark
+        """
+        if section_name in self.customizations:
+            self.customizations.remove(section_name)
+
+    def has_customizations(self) -> bool:
+        """Check if any customizations exist.
+
+        Returns:
+            True if user has customized documentation
+        """
+        return len(self.customizations) > 0

htmlgraph/docs/migrations.py

@@ -0,0 +1,232 @@
+"""
+Documentation migration system.
+
+Handles version migrations with automatic customization preservation.
+"""
+
+import shutil
+from abc import ABC, abstractmethod
+from datetime import datetime
+from pathlib import Path
+
+from htmlgraph.docs.metadata import DocsMetadata
+
+
+class MigrationScript(ABC):
+    """Base class for documentation migrations."""
+
+    from_version: int
+    to_version: int
+
+    @abstractmethod
+    def migrate(self, htmlgraph_dir: Path, backup_dir: Path) -> bool:
+        """Execute migration. Returns True if successful.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+
+        Returns:
+            True if migration successful
+        """
+        pass
+
+    @abstractmethod
+    def rollback(self, htmlgraph_dir: Path, backup_dir: Path) -> None:
+        """Rollback migration to previous state.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+        """
+        pass
+
+    def backup_docs(self, htmlgraph_dir: Path, backup_dir: Path) -> Path:
+        """Backup current documentation before migration.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+
+        Returns:
+            Path to created backup subdirectory
+        """
+        backup_subdir = (
+            backup_dir / f"v{self.from_version}_{datetime.now():%Y%m%d_%H%M%S}"
+        )
+        backup_subdir.mkdir(parents=True, exist_ok=True)
+
+        # Backup all docs
+        docs_dir = htmlgraph_dir / "docs"
+        if docs_dir.exists():
+            for doc_file in docs_dir.glob("*.md"):
+                shutil.copy2(doc_file, backup_subdir / doc_file.name)
+
+        # Also backup root-level docs (legacy)
+        for doc_file in htmlgraph_dir.glob("*.md"):
+            shutil.copy2(doc_file, backup_subdir / doc_file.name)
+
+        return backup_subdir
+
+
+class V1toV2Migration(MigrationScript):
+    """Migrate from v1 (root-level docs) to v2 (template-based docs)."""
+
+    from_version = 1
+    to_version = 2
+
+    def migrate(self, htmlgraph_dir: Path, backup_dir: Path) -> bool:
+        """Migrate v1 docs to v2 template structure.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+
+        Returns:
+            True if migration successful
+        """
+        # Backup first
+        backup_path = self.backup_docs(htmlgraph_dir, backup_dir)
+        print(f"✅ Backed up to {backup_path}")
+
+        # Detect user customizations in old AGENTS.md
+        customizations = self._detect_customizations(htmlgraph_dir / "AGENTS.md")
+        if customizations:
+            print(f"📝 Detected customizations: {', '.join(customizations)}")
+
+        # Move old docs to archive
+        old_agents_md = htmlgraph_dir / "AGENTS.md"
+        if old_agents_md.exists():
+            old_agents_md.rename(htmlgraph_dir / "AGENTS.md.v1.backup")
+            print("📦 Archived old AGENTS.md")
+
+        # Generate new v2 docs with customizations preserved
+        self._generate_v2_docs(htmlgraph_dir, customizations)
+        print("✨ Generated v2 documentation")
+
+        # Update metadata
+        metadata = DocsMetadata.load(htmlgraph_dir)
+        metadata.schema_version = 2
+        metadata.customizations = customizations
+        metadata.save(htmlgraph_dir)
+        print("💾 Updated metadata")
+
+        return True
+
+    def _detect_customizations(self, agents_md_path: Path) -> list[str]:
+        """Detect user-customized sections in old AGENTS.md.
+
+        Args:
+            agents_md_path: Path to AGENTS.md file
+
+        Returns:
+            List of customized section names
+        """
+        if not agents_md_path.exists():
+            return []
+
+        content = agents_md_path.read_text()
+        customizations = []
+
+        # Simple heuristic: sections not in base template
+        if "## Our Team" in content:
+            customizations.append("custom_workflows")
+        if "## Project Conventions" in content:
+            customizations.append("project_conventions")
+        if "## Custom Workflows" in content:
+            customizations.append("custom_workflows")
+
+        return customizations
+
+    def _generate_v2_docs(self, htmlgraph_dir: Path, customizations: list[str]) -> None:
+        """Generate v2 template-based docs with customizations.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            customizations: List of customized sections to preserve
+        """
+        # NOTE: This would integrate with sync_docs.py
+        # For now, just create placeholder
+        docs_dir = htmlgraph_dir / "docs"
+        docs_dir.mkdir(exist_ok=True)
+
+        placeholder = docs_dir / "AGENTS.md"
+        placeholder.write_text(
+            """# HtmlGraph Agent Documentation (v2)
+
+This file was migrated from v1 to v2.
+
+Run `uv run htmlgraph sync-docs` to regenerate from templates.
+"""
+        )
+
+        # Inject customizations as template overrides if needed
+        if customizations:
+            self._create_override_template(htmlgraph_dir, customizations)
+
+    def _create_override_template(
+        self, htmlgraph_dir: Path, customizations: list[str]
+    ) -> None:
+        """Create template overrides for customizations.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            customizations: List of customizations to preserve
+        """
+        overrides_file = htmlgraph_dir / "docs" / "overrides.md"
+        overrides_file.write_text(
+            f"""# Documentation Customizations
+
+The following sections were customized in v1:
+
+{chr(10).join(f"- {c}" for c in customizations)}
+
+To preserve these customizations, add them back manually after running sync-docs.
+"""
+        )
+
+    def rollback(self, htmlgraph_dir: Path, backup_dir: Path) -> None:
+        """Rollback to v1 docs from backup.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+            backup_dir: Path to backup directory
+        """
+        # Find latest backup
+        backups = sorted(backup_dir.glob("v1_*"))
+        if not backups:
+            raise ValueError("No backup found for rollback")
+
+        latest_backup = backups[-1]
+        print(f"🔄 Rolling back from {latest_backup}")
+
+        # Restore old AGENTS.md
+        backup_agents = latest_backup / "AGENTS.md"
+        if backup_agents.exists():
+            shutil.copy2(backup_agents, htmlgraph_dir / "AGENTS.md")
+            print("✅ Restored AGENTS.md")
+
+        # Update metadata
+        metadata = DocsMetadata.load(htmlgraph_dir)
+        metadata.schema_version = 1
+        metadata.save(htmlgraph_dir)
+        print("💾 Updated metadata to v1")
+
+
+# Migration registry
+MIGRATIONS: dict[tuple[int, int], MigrationScript] = {
+    (1, 2): V1toV2Migration(),
+}
+
+
+def get_migration(from_version: int, to_version: int) -> MigrationScript | None:
+    """Get migration script for version transition.
+
+    Args:
+        from_version: Source schema version
+        to_version: Target schema version
+
+    Returns:
+        MigrationScript instance or None if no migration exists
+    """
+    return MIGRATIONS.get((from_version, to_version))

htmlgraph/docs/template_engine.py

@@ -0,0 +1,143 @@
+"""Jinja2-based template engine for documentation with user customization."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from jinja2 import ChoiceLoader, Environment, FileSystemLoader
+
+
+class DocTemplateEngine:
+    """Renders documentation templates with user customization support.
+
+    Template Priority:
+    1. User templates in .htmlgraph/docs/templates/ (highest priority)
+    2. Package templates in htmlgraph/docs/templates/ (fallback)
+
+    Example:
+        >>> engine = DocTemplateEngine(Path(".htmlgraph"))
+        >>> content = engine.render_agents_md("0.21.0", "claude")
+        >>> print(content)
+    """
+
+    def __init__(self, htmlgraph_dir: Path):
+        """Initialize template engine with multi-loader.
+
+        Args:
+            htmlgraph_dir: Path to .htmlgraph directory
+        """
+        # Package templates (bundled with pip install)
+        package_templates = Path(__file__).parent / "templates"
+
+        # User templates (project-specific customizations)
+        user_templates = htmlgraph_dir / "docs" / "templates"
+
+        # Multi-loader: User templates have priority over package templates
+        loaders = []
+        if user_templates.exists():
+            loaders.append(FileSystemLoader(str(user_templates)))
+        loaders.append(FileSystemLoader(str(package_templates)))
+
+        self.env = Environment(loader=ChoiceLoader(loaders))
+
+        # Add custom filters
+        self.env.filters["format_date"] = self._format_date
+        self.env.filters["highlight_code"] = self._highlight_code
+
+    def render(self, template_name: str, context: dict[str, Any]) -> str:
+        """Render template with context, merging user overrides.
+
+        Args:
+            template_name: Name of template file (e.g., "agents.md.j2")
+            context: Template variables
+
+        Returns:
+            Rendered content with user customizations applied
+
+        Example:
+            >>> engine.render("agents.md.j2", {"platform": "claude"})
+        """
+        template = self.env.get_template(template_name)
+        return template.render(**context)
+
+    def render_agents_md(self, sdk_version: str, platform: str = "claude") -> str:
+        """Render AGENTS.md with platform-specific customizations.
+
+        Args:
+            sdk_version: HtmlGraph SDK version (e.g., "0.21.0")
+            platform: Platform name (claude, gemini, api, etc.)
+
+        Returns:
+            Rendered AGENTS.md content
+
+        Example:
+            >>> content = engine.render_agents_md("0.21.0", "claude")
+        """
+        context = {
+            "sdk_version": sdk_version,
+            "platform": platform,
+            "features_enabled": self._get_enabled_features(),
+            "custom_workflows": self._load_custom_workflows(),
+            "generated_at": datetime.now().isoformat(),
+        }
+        # User templates should extend "base_agents.md.j2" to avoid recursion
+        # Priority: agents.md.j2 (user override) → base_agents.md.j2 (package default)
+        template_name = "agents.md.j2"
+        try:
+            # Try to get user template first (will succeed if it exists in user dir)
+            self.env.get_template(template_name)
+            return self.render(template_name, context)
+        except:  # noqa
+            # Fall back to base template (always exists in package)
+            return self.render("base_agents.md.j2", context)
+
+    def _format_date(self, value: str) -> str:
+        """Format ISO date string for display.
+
+        Args:
+            value: ISO 8601 date string
+
+        Returns:
+            Formatted date string
+        """
+        try:
+            dt = datetime.fromisoformat(value)
+            return dt.strftime("%Y-%m-%d %H:%M")
+        except (ValueError, AttributeError):
+            return value
+
+    def _highlight_code(self, code: str, language: str = "python") -> str:
+        """Add markdown code fence with syntax highlighting.
+
+        Args:
+            code: Code snippet
+            language: Programming language for syntax highlighting
+
+        Returns:
+            Markdown code block
+        """
+        return f"```{language}\n{code}\n```"
+
+    def _get_enabled_features(self) -> dict[str, bool]:
+        """Get enabled features for this installation.
+
+        Returns:
+            Dictionary of feature flags
+        """
+        # TODO: Read from config or detect dynamically
+        return {
+            "sessions": True,
+            "tracks": True,
+            "analytics": True,
+            "mcp": True,
+            "cli": True,
+        }
+
+    def _load_custom_workflows(self) -> str | None:
+        """Load custom workflows from user template.
+
+        Returns:
+            Custom workflow markdown or None
+        """
+        # TODO: Load from .htmlgraph/docs/workflows.md if exists
+        return None