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

htmlgraph/docs/version_check.py

@@ -0,0 +1,161 @@
+"""
+Version checking and interactive upgrade workflows.
+"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from htmlgraph.docs.docs_version import get_current_doc_version, is_compatible
+from htmlgraph.docs.metadata import DocsMetadata
+from htmlgraph.docs.migrations import get_migration
+
+if TYPE_CHECKING:
+    from htmlgraph.docs.migrations import MigrationScript
+
+
+def check_docs_version(htmlgraph_dir: Path) -> tuple[bool, str | None]:
+    """Check if docs version is compatible.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+
+    Returns:
+        Tuple of (is_compatible, message)
+        - is_compatible: True if compatible
+        - message: Optional warning/error message
+    """
+    metadata = DocsMetadata.load(htmlgraph_dir)
+    current_version = get_current_doc_version()
+
+    if metadata.schema_version == current_version:
+        return True, None
+
+    if is_compatible(metadata.schema_version, current_version):
+        return (
+            True,
+            f"⚠️  Docs version {metadata.schema_version} is supported but outdated (current: {current_version})",
+        )
+
+    return (
+        False,
+        f"❌ Docs version {metadata.schema_version} is incompatible with package (requires: {current_version})",
+    )
+
+
+def upgrade_docs_interactive(htmlgraph_dir: Path) -> None:
+    """Interactive upgrade workflow with user prompts.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+    """
+    metadata = DocsMetadata.load(htmlgraph_dir)
+    current_version = get_current_doc_version()
+
+    if metadata.schema_version == current_version:
+        print("✅ Docs are up to date")
+        return
+
+    # Get migration script
+    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}"
+        )
+        return
+
+    # Show user their options
+    print(
+        f"""
+📋 Documentation Upgrade Available
+  Current: v{metadata.schema_version}
+  Target:  v{current_version}
+
+  Options:
+    1. Auto-migrate (preserves customizations)
+    2. Side-by-side (test before committing)
+    3. Manual migration (view diff first)
+    4. Skip (stay on v{metadata.schema_version})
+  """
+    )
+
+    choice = input("Choose option (1-4): ").strip()
+
+    if choice == "1":
+        _auto_migrate(htmlgraph_dir, migration)
+    elif choice == "2":
+        _side_by_side_migrate(htmlgraph_dir, migration)
+    elif choice == "3":
+        _show_diff_for_manual(htmlgraph_dir, migration)
+    else:
+        print("⏭️  Skipping migration")
+
+
+def _auto_migrate(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Automatically migrate with backup.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    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. Docs unchanged.")
+
+
+def _side_by_side_migrate(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Create side-by-side versions for testing.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    print("📋 Creating side-by-side versions...")
+    print("⚠️  Side-by-side migration not yet implemented")
+    print("    Use option 1 (auto-migrate) or 3 (manual) instead")
+
+
+def _show_diff_for_manual(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Show diff preview for manual migration.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    print("📊 Showing migration preview...")
+    print("⚠️  Diff preview not yet implemented")
+    print("    Use option 1 (auto-migrate) instead")
+
+
+def check_version_on_init(htmlgraph_dir: Path, auto_upgrade: bool = False) -> bool:
+    """Check version compatibility on SDK initialization.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        auto_upgrade: If True, automatically upgrade if safe
+
+    Returns:
+        True if compatible or upgraded successfully
+    """
+    compatible, message = check_docs_version(htmlgraph_dir)
+
+    if compatible and message:
+        # Compatible but outdated
+        print(message)
+        if auto_upgrade:
+            upgrade_docs_interactive(htmlgraph_dir)
+        return True
+
+    if not compatible:
+        print(message)
+        print("\nRun `uv run htmlgraph docs upgrade` to migrate.")
+        return False
+
+    return True

{htmlgraph-0.21.0.dist-info → htmlgraph-0.22.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.21.0
+Version: 0.22.0
 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

{htmlgraph-0.21.0.dist-info → htmlgraph-0.22.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-htmlgraph/__init__.py,sha256=AbgvM2vQ2nTI1DHlLsxmhhXZgrxmLxgwr5stbc25ZSc,4979
+htmlgraph/__init__.py,sha256=NwNZ7Guk6B_uFRH7q8QwxYLn3opbpc3SQ89r3QPDoVQ,4979
 htmlgraph/agent_detection.py,sha256=PAYo7rU3N_y1cGRd7Dwjh5Wgu-QZ7ENblX_yOzU-gJ0,2749
 htmlgraph/agent_registry.py,sha256=Usa_35by7p5gtpvHO7K3AcGimnorw-FzgPVa3cWTQ58,9448
 htmlgraph/agents.py,sha256=Yvu6x1nOfrW2WhRTAHiCuSpvqoVJXx1Mkzd59kwEczw,33466
 htmlgraph/analytics_index.py,sha256=ba6Y4H_NNOCxI_Z4U7wSgBFFairf4IJT74WcM1PoZuI,30594
 htmlgraph/attribute_index.py,sha256=cBZUV4YfGnhh6lF59aYPCdNrRr1hK__BzSKCueSDUhQ,6593
-htmlgraph/cli.py,sha256=6CwzcFZ6tOlYCS1521gvFkwVw4qb9XSLvq-eqb2Mz8I,182068
+htmlgraph/cli.py,sha256=cWmJLbUODzZxNI99TslGGLjE-u_PBHhayoRtuafS5RQ,190277
 htmlgraph/context_analytics.py,sha256=CaLu0o2uSr6rlBM5YeaFZe7grgsy7_Hx10qdXuNcdao,11344
 htmlgraph/converter.py,sha256=OfcydZcJqvr2jpMxvAD4wcq8o4NXC7w4X4QzdDiYq8k,22277
 htmlgraph/dashboard.html,sha256=rkZYjSnPbUuAm35QMpCNWemenYqQTdkkumCX2hhe8Dc,173537
@@ -82,6 +82,17 @@ htmlgraph/collections/pattern.py,sha256=FkEqF0eoMoluJxvpiZZ3OZnZNxMc24kzTL0Zmvyi
 htmlgraph/collections/phase.py,sha256=2GcgD-P-j61jgG4c0VhUmsOp1qjtrJLtRDNumHHDNZA,1359
 htmlgraph/collections/spike.py,sha256=Omazli2JM9RoYgseSAxKYeK4KC8mAwMCfUAF1XFml54,2963
 htmlgraph/collections/todo.py,sha256=SWOkolqCIvf7PCxCLuqPuNCpdDSTOc9KsuaXanWSEFY,15548
+htmlgraph/docs/__init__.py,sha256=WlDS4y_DgpkoXQbJMucUjkCwyQs60t_QySI9m1CaMKU,2106
+htmlgraph/docs/docs_version.py,sha256=4rXIhuhKv7VDGRlNtvWyB4zPboNGtcGfJjbf0yf1sI0,1475
+htmlgraph/docs/metadata.py,sha256=sUlbIEqysXRma99a2KLSfJ-NqPYfz5p2pSj-s8wPblQ,2708
+htmlgraph/docs/migrations.py,sha256=-kCWXOmilJKXCxe1LKob8sfVCQhcWambEa9asTCobKg,7248
+htmlgraph/docs/template_engine.py,sha256=aRr7hUcCoXOPzZlxifmxNr3nImOvla-X3qYYWKfXDMw,4825
+htmlgraph/docs/version_check.py,sha256=4zhplgv42k8REik4fU9Q2LANZoSRv7uSzGQGdVKj5VI,4892
+htmlgraph/docs/templates/base_agents.md.j2,sha256=s3qyWyx4XWkeeqmWGtnsK0AsDOhBA108Cc2lbA08VfE,1713
+htmlgraph/docs/templates/example_user_override.md.j2,sha256=BYm_p9qP21hjAF7zwGfx1NU8PTlQ00yphk-leHsMHDY,1361
+htmlgraph/docs/templates/_sections/cli_reference.md.j2,sha256=TItgng09Qxre2EdqXdq-R2RhS9IW5W7mis-vjpWGKA4,806
+htmlgraph/docs/templates/_sections/core_concepts.md.j2,sha256=7kkyaKiKOqMg5NF_IIRxdDk5RGfq0vnRZd6ZBI5_mUE,738
+htmlgraph/docs/templates/_sections/sdk_basics.md.j2,sha256=XEL90BQvTKa4xiWkCO96CT9ddp47IiBOoMDrpZOL2B0,1334
 htmlgraph/extensions/gemini/GEMINI.md,sha256=fRUP-u1UmUTuRVbQ32sK3iYQAFYGYRyjU0W0_igT6GA,20462
 htmlgraph/extensions/gemini/README.md,sha256=PDWQDi6IA8Jq6ZMrEn9jpLygbSjp41Chtl2wGSm5Y1c,7116
 htmlgraph/extensions/gemini/gemini-extension.json,sha256=-CU-34hZkmw8gx-Tdojjuytf12LfArzCBMVFyc8X_Eo,493
@@ -113,12 +124,12 @@ htmlgraph/services/claiming.py,sha256=HcrltEJKN72mxuD7fGuXWeh1U0vwhjMvhZcFc02Eiy
 htmlgraph/templates/AGENTS.md.template,sha256=f96h7V6ygwj-v-fanVI48eYMxR6t_se4bet1H4ZsDpI,7642
 htmlgraph/templates/CLAUDE.md.template,sha256=h1kG2hTX2XYig2KszsHBfzrwa_4Cfcq2Pj4SwqzeDlM,1984
 htmlgraph/templates/GEMINI.md.template,sha256=gAGzE53Avki87BM_otqy5HdcYCoLsHgqaKjVzNzPMX8,1622
-htmlgraph-0.21.0.data/data/htmlgraph/dashboard.html,sha256=rkZYjSnPbUuAm35QMpCNWemenYqQTdkkumCX2hhe8Dc,173537
-htmlgraph-0.21.0.data/data/htmlgraph/styles.css,sha256=oDUSC8jG-V-hKojOBO9J88hxAeY2wJrBYTq0uCwX_Y4,7135
-htmlgraph-0.21.0.data/data/htmlgraph/templates/AGENTS.md.template,sha256=f96h7V6ygwj-v-fanVI48eYMxR6t_se4bet1H4ZsDpI,7642
-htmlgraph-0.21.0.data/data/htmlgraph/templates/CLAUDE.md.template,sha256=h1kG2hTX2XYig2KszsHBfzrwa_4Cfcq2Pj4SwqzeDlM,1984
-htmlgraph-0.21.0.data/data/htmlgraph/templates/GEMINI.md.template,sha256=gAGzE53Avki87BM_otqy5HdcYCoLsHgqaKjVzNzPMX8,1622
-htmlgraph-0.21.0.dist-info/METADATA,sha256=imvjH4WNDmGZNWZ9atUaBoHlxiOfjlAxGrzE0XfHoY8,7645
-htmlgraph-0.21.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-htmlgraph-0.21.0.dist-info/entry_points.txt,sha256=EaUbjA_bbDwEO_XDLEGMeK8aQP-ZnHiUTkLshyKDyB8,98
-htmlgraph-0.21.0.dist-info/RECORD,,
+htmlgraph-0.22.0.data/data/htmlgraph/dashboard.html,sha256=rkZYjSnPbUuAm35QMpCNWemenYqQTdkkumCX2hhe8Dc,173537
+htmlgraph-0.22.0.data/data/htmlgraph/styles.css,sha256=oDUSC8jG-V-hKojOBO9J88hxAeY2wJrBYTq0uCwX_Y4,7135
+htmlgraph-0.22.0.data/data/htmlgraph/templates/AGENTS.md.template,sha256=f96h7V6ygwj-v-fanVI48eYMxR6t_se4bet1H4ZsDpI,7642
+htmlgraph-0.22.0.data/data/htmlgraph/templates/CLAUDE.md.template,sha256=h1kG2hTX2XYig2KszsHBfzrwa_4Cfcq2Pj4SwqzeDlM,1984
+htmlgraph-0.22.0.data/data/htmlgraph/templates/GEMINI.md.template,sha256=gAGzE53Avki87BM_otqy5HdcYCoLsHgqaKjVzNzPMX8,1622
+htmlgraph-0.22.0.dist-info/METADATA,sha256=F9jdZlZyFDN5s8kmlCHt6-vooZMxu_Gkc2OwAJljNYE,7645
+htmlgraph-0.22.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+htmlgraph-0.22.0.dist-info/entry_points.txt,sha256=EaUbjA_bbDwEO_XDLEGMeK8aQP-ZnHiUTkLshyKDyB8,98
+htmlgraph-0.22.0.dist-info/RECORD,,