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

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.21.0"
+__version__ = "0.22.0"
 __all__ = [
     # Exceptions
     "HtmlGraphError",

htmlgraph/cli.py

@@ -2164,6 +2164,173 @@ def cmd_track(args: argparse.Namespace) -> None:
             print(f"  Drift warning: {entry.drift_score:.2f}")
 
 
+# =============================================================================
+# Documentation Version Management Commands
+# =============================================================================
+
+
+def cmd_docs_version(args: argparse.Namespace) -> None:
+    """Check documentation version compatibility."""
+    from htmlgraph.docs import check_docs_version
+
+    htmlgraph_dir = Path(args.graph_dir)
+
+    if not htmlgraph_dir.exists():
+        print(f"❌ Directory not found: {htmlgraph_dir}")
+        print("   Run `htmlgraph init` first")
+        sys.exit(1)
+
+    compatible, message = check_docs_version(htmlgraph_dir)
+
+    if compatible and not message:
+        print("✅ Documentation is up to date")
+    elif compatible and message:
+        print(message)
+        print("\n💡 Run `htmlgraph docs upgrade` to update to latest version")
+    else:
+        print(message)
+        print("\n❌ Documentation version is incompatible")
+        print("   Run `htmlgraph docs upgrade` to migrate")
+        sys.exit(1)
+
+
+def cmd_docs_upgrade(args: argparse.Namespace) -> None:
+    """Upgrade documentation to latest version."""
+    from htmlgraph.docs import upgrade_docs_interactive
+    from htmlgraph.docs.docs_version import get_current_doc_version
+    from htmlgraph.docs.metadata import DocsMetadata
+    from htmlgraph.docs.migrations import get_migration
+
+    htmlgraph_dir = Path(args.graph_dir)
+
+    if not htmlgraph_dir.exists():
+        print(f"❌ Directory not found: {htmlgraph_dir}")
+        print("   Run `htmlgraph init` first")
+        sys.exit(1)
+
+    if args.auto:
+        # Auto-migrate without prompts
+        metadata = DocsMetadata.load(htmlgraph_dir)
+        current_version = get_current_doc_version()
+
+        if metadata.schema_version == current_version:
+            print("✅ Documentation is already up to date")
+            return
+
+        migration = get_migration(metadata.schema_version, current_version)
+        if not migration:
+            print(
+                f"❌ No migration available from v{metadata.schema_version} to v{current_version}"
+            )
+            sys.exit(1)
+
+        backup_dir = htmlgraph_dir / ".docs-backups"
+        backup_dir.mkdir(exist_ok=True)
+
+        print("🚀 Starting auto-migration...")
+        success = migration.migrate(htmlgraph_dir, backup_dir)
+
+        if success:
+            print("✅ Migration complete!")
+            print(f"📦 Backup saved to {backup_dir}")
+        else:
+            print("❌ Migration failed")
+            sys.exit(1)
+    else:
+        # Interactive upgrade
+        upgrade_docs_interactive(htmlgraph_dir)
+
+
+def cmd_docs_diff(args: argparse.Namespace) -> None:
+    """Show migration diff preview."""
+    htmlgraph_dir = Path(args.graph_dir)
+
+    if not htmlgraph_dir.exists():
+        print(f"❌ Directory not found: {htmlgraph_dir}")
+        print("   Run `htmlgraph init` first")
+        sys.exit(1)
+
+    print("📊 Showing migration preview...")
+    print("⚠️  Diff preview not yet implemented")
+    print("    Use `htmlgraph docs upgrade` instead")
+
+
+def cmd_docs_rollback(args: argparse.Namespace) -> None:
+    """Rollback to previous documentation version."""
+    from htmlgraph.docs.metadata import DocsMetadata
+    from htmlgraph.docs.migrations import get_migration
+
+    htmlgraph_dir = Path(args.graph_dir)
+
+    if not htmlgraph_dir.exists():
+        print(f"❌ Directory not found: {htmlgraph_dir}")
+        print("   Run `htmlgraph init` first")
+        sys.exit(1)
+
+    backup_dir = htmlgraph_dir / ".docs-backups"
+    if not backup_dir.exists() or not list(backup_dir.glob("v*")):
+        print("❌ No backups found")
+        print("   Nothing to rollback to")
+        sys.exit(1)
+
+    # Get target version
+    metadata = DocsMetadata.load(htmlgraph_dir)
+    target_version = int(args.version) if args.version else metadata.schema_version - 1
+
+    if target_version < 1:
+        print("❌ Invalid version")
+        sys.exit(1)
+
+    # Get migration script
+    migration = get_migration(target_version, metadata.schema_version)
+    if not migration:
+        print(
+            f"❌ Cannot rollback from v{metadata.schema_version} to v{target_version}"
+        )
+        sys.exit(1)
+
+    print(f"🔄 Rolling back to v{target_version}...")
+    try:
+        migration.rollback(htmlgraph_dir, backup_dir)
+        print("✅ Rollback complete")
+    except Exception as e:
+        print(f"❌ Rollback failed: {e}")
+        sys.exit(1)
+
+
+def cmd_docs_generate(args: argparse.Namespace) -> None:
+    """Generate documentation from templates with user customizations."""
+    from htmlgraph.docs import sync_docs_to_file
+
+    htmlgraph_dir = Path(args.graph_dir)
+    output_file = Path(args.output) if args.output else Path("AGENTS.md")
+    platform = args.platform
+
+    if not htmlgraph_dir.exists():
+        print(f"❌ Directory not found: {htmlgraph_dir}")
+        print("   Run `htmlgraph init` first")
+        sys.exit(1)
+
+    try:
+        print(f"📝 Generating documentation for platform: {platform}")
+        print(f"   Output: {output_file}")
+
+        result_path = sync_docs_to_file(htmlgraph_dir, output_file, platform)
+
+        print(f"✅ Documentation generated: {result_path}")
+        print("\n💡 To customize:")
+        print(f"   1. Create {htmlgraph_dir}/docs/templates/agents.md.j2")
+        print("   2. Extend base template: {% extends 'base_agents.md.j2' %}")
+        print("   3. Override blocks: header, introduction, custom_workflows, etc.")
+
+    except Exception as e:
+        print(f"❌ Generation failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        sys.exit(1)
+
+
 # =============================================================================
 # Events & Index Commands
 # =============================================================================
@@ -4428,6 +4595,64 @@ For more help: https://github.com/Shakes-tzd/htmlgraph
         "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
     )
 
+    # =========================================================================
+    # Documentation Version Management
+    # =========================================================================
+
+    docs_parser = subparsers.add_parser("docs", help="Documentation version management")
+    docs_subparsers = docs_parser.add_subparsers(
+        dest="docs_command", help="Docs command"
+    )
+
+    docs_version = docs_subparsers.add_parser(
+        "version", help="Check documentation version compatibility"
+    )
+    docs_version.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+
+    docs_upgrade = docs_subparsers.add_parser(
+        "upgrade", help="Upgrade documentation to latest version"
+    )
+    docs_upgrade.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+    docs_upgrade.add_argument(
+        "--auto", action="store_true", help="Auto-migrate without prompts"
+    )
+
+    docs_diff = docs_subparsers.add_parser("diff", help="Show migration diff preview")
+    docs_diff.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+
+    docs_rollback = docs_subparsers.add_parser(
+        "rollback", help="Rollback to previous version"
+    )
+    docs_rollback.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+    docs_rollback.add_argument(
+        "version", nargs="?", help="Version to rollback to (default: latest backup)"
+    )
+
+    docs_generate = docs_subparsers.add_parser(
+        "generate", help="Generate documentation from templates"
+    )
+    docs_generate.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+    docs_generate.add_argument(
+        "--platform",
+        "-p",
+        default="claude",
+        choices=["claude", "gemini", "api", "cli"],
+        help="Platform to generate docs for",
+    )
+    docs_generate.add_argument(
+        "--output", "-o", help="Output file (default: AGENTS.md)"
+    )
+
     # =========================================================================
     # Events & Analytics Index
     # =========================================================================
@@ -4840,6 +5065,20 @@ For more help: https://github.com/Shakes-tzd/htmlgraph
         from htmlgraph.analytics.cli import cmd_analytics
 
         cmd_analytics(args)
+    elif args.command == "docs":
+        if args.docs_command == "version":
+            cmd_docs_version(args)
+        elif args.docs_command == "upgrade":
+            cmd_docs_upgrade(args)
+        elif args.docs_command == "diff":
+            cmd_docs_diff(args)
+        elif args.docs_command == "rollback":
+            cmd_docs_rollback(args)
+        elif args.docs_command == "generate":
+            cmd_docs_generate(args)
+        else:
+            docs_parser.print_help()
+            sys.exit(1)
     elif args.command == "events":
         if args.events_command == "export-sessions":
             cmd_events_export(args)

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