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

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
 # =============================================================================
@@ -4326,6 +4493,87 @@ For more help: https://github.com/Shakes-tzd/htmlgraph
         "--format", "-f", choices=["text", "json"], default="text", help="Output format"
     )
 
+    # =========================================================================
+    # Archive Management
+    # =========================================================================
+
+    # archive (with subcommands)
+    archive_parser = subparsers.add_parser(
+        "archive", help="Archive management with optimized search"
+    )
+    archive_subparsers = archive_parser.add_subparsers(
+        dest="archive_command", help="Archive command"
+    )
+
+    # archive create
+    archive_create = archive_subparsers.add_parser(
+        "create", help="Create archive from old entities"
+    )
+    archive_create.add_argument(
+        "--older-than",
+        type=int,
+        default=90,
+        help="Archive entities older than N days (default: 90)",
+    )
+    archive_create.add_argument(
+        "--period",
+        choices=["quarter", "month", "year"],
+        default="quarter",
+        help="Archive grouping period (default: quarter)",
+    )
+    archive_create.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview what would be archived without making changes",
+    )
+    archive_create.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+
+    # archive search
+    archive_search = archive_subparsers.add_parser(
+        "search", help="Search archived entities"
+    )
+    archive_search.add_argument("query", help="Search query")
+    archive_search.add_argument(
+        "--limit", "-l", type=int, default=10, help="Maximum results (default: 10)"
+    )
+    archive_search.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+    archive_search.add_argument(
+        "--format", "-f", choices=["text", "json"], default="text", help="Output format"
+    )
+
+    # archive stats
+    archive_stats = archive_subparsers.add_parser(
+        "stats", help="Show archive statistics"
+    )
+    archive_stats.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+    archive_stats.add_argument(
+        "--format", "-f", choices=["text", "json"], default="text", help="Output format"
+    )
+
+    # archive restore
+    archive_restore = archive_subparsers.add_parser(
+        "restore", help="Restore archived entity"
+    )
+    archive_restore.add_argument("entity_id", help="Entity ID to restore")
+    archive_restore.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+
+    # archive list
+    archive_list = archive_subparsers.add_parser("list", help="List all archive files")
+    archive_list.add_argument(
+        "--graph-dir", "-g", default=".htmlgraph", help="Graph directory"
+    )
+    archive_list.add_argument(
+        "--format", "-f", choices=["text", "json"], default="text", help="Output format"
+    )
+
     # =========================================================================
     # Analytics
     # =========================================================================
@@ -4347,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
     # =========================================================================
@@ -4700,6 +5006,21 @@ For more help: https://github.com/Shakes-tzd/htmlgraph
         else:
             track_parser.print_help()
             sys.exit(1)
+    elif args.command == "archive":
+        # Archive management
+        if args.archive_command == "create":
+            cmd_archive_create(args)
+        elif args.archive_command == "search":
+            cmd_archive_search(args)
+        elif args.archive_command == "stats":
+            cmd_archive_stats(args)
+        elif args.archive_command == "restore":
+            cmd_archive_restore(args)
+        elif args.archive_command == "list":
+            cmd_archive_list(args)
+        else:
+            archive_parser.print_help()
+            sys.exit(1)
     elif args.command == "work":
         # Work management with smart routing
         if args.work_command == "next":
@@ -4744,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)
@@ -4971,5 +5306,180 @@ def cmd_sync_docs(args: argparse.Namespace) -> int:
         return 1 if any("⚠️" in c or "❌" in c for c in changes) else 0
 
 
+# =============================================================================
+# Archive Management Commands
+# =============================================================================
+
+
+def cmd_archive_create(args: argparse.Namespace) -> None:
+    """Create archive from old entities."""
+    from pathlib import Path
+
+    from htmlgraph.archive import ArchiveManager
+
+    htmlgraph_dir = Path(args.graph_dir).resolve()
+
+    if not htmlgraph_dir.exists():
+        print(f"Error: Directory not found: {htmlgraph_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    manager = ArchiveManager(htmlgraph_dir)
+
+    # Run archive operation
+    result = manager.archive_entities(
+        older_than_days=args.older_than,
+        period=args.period,
+        dry_run=args.dry_run,
+    )
+
+    if result["dry_run"]:
+        print("\n🔍 DRY RUN - Preview (no changes made)\n")
+        print(f"Would archive: {result['would_archive']} entities")
+        print(f"Archive files: {len(result['archive_files'])}")
+        print("\nDetails:")
+        for archive_key, count in result["details"].items():
+            print(f"  {archive_key}: {count} entities")
+    else:
+        print(f"\n✅ Archived {result['archived_count']} entities")
+        print(f"Created {len(result['archive_files'])} archive file(s):")
+        for archive_file in result["archive_files"]:
+            count = result["details"].get(archive_file.replace(".html", ""), 0)
+            print(f"  - {archive_file} ({count} entities)")
+
+    manager.close()
+
+
+def cmd_archive_search(args: argparse.Namespace) -> None:
+    """Search archived entities."""
+    import json
+    from pathlib import Path
+
+    from htmlgraph.archive import ArchiveManager
+
+    htmlgraph_dir = Path(args.graph_dir).resolve()
+
+    if not htmlgraph_dir.exists():
+        print(f"Error: Directory not found: {htmlgraph_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    manager = ArchiveManager(htmlgraph_dir)
+
+    # Search archives
+    results = manager.search(args.query, limit=args.limit)
+
+    if args.format == "json":
+        print(json.dumps({"query": args.query, "results": results}, indent=2))
+    else:
+        print(f"\n🔍 Search results for: '{args.query}'\n")
+        print(f"Found {len(results)} result(s):\n")
+
+        for i, result in enumerate(results, 1):
+            print(f"{i}. {result['entity_id']} ({result['entity_type']})")
+            print(f"   Archive: {result['archive_file']}")
+            print(f"   Status: {result['status']}")
+            print(f"   Title: {result['title_snippet']}")
+            if result["description_snippet"]:
+                print(f"   Description: {result['description_snippet']}")
+            print(f"   Relevance: {result['rank']:.2f}")
+            print()
+
+    manager.close()
+
+
+def cmd_archive_stats(args: argparse.Namespace) -> None:
+    """Show archive statistics."""
+    import json
+    from pathlib import Path
+
+    from htmlgraph.archive import ArchiveManager
+
+    htmlgraph_dir = Path(args.graph_dir).resolve()
+
+    if not htmlgraph_dir.exists():
+        print(f"Error: Directory not found: {htmlgraph_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    manager = ArchiveManager(htmlgraph_dir)
+
+    # Get statistics
+    stats = manager.get_archive_stats()
+
+    if args.format == "json":
+        print(json.dumps(stats, indent=2))
+    else:
+        print("\n📊 Archive Statistics\n")
+        print(f"Archive files: {stats['archive_count']}")
+        print(f"Archived entities: {stats['entity_count']}")
+        print(f"Total size: {stats['total_size_mb']:.2f} MB")
+        print(f"FTS5 index: {stats['fts_size_mb']:.2f} MB")
+        print(
+            f"Bloom filters: {stats['bloom_size_kb']:.2f} KB ({stats['bloom_count']} files)"
+        )
+
+    manager.close()
+
+
+def cmd_archive_restore(args: argparse.Namespace) -> None:
+    """Restore archived entity."""
+    from pathlib import Path
+
+    from htmlgraph.archive import ArchiveManager
+
+    htmlgraph_dir = Path(args.graph_dir).resolve()
+
+    if not htmlgraph_dir.exists():
+        print(f"Error: Directory not found: {htmlgraph_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    manager = ArchiveManager(htmlgraph_dir)
+
+    # Restore entity
+    success = manager.unarchive(args.entity_id)
+
+    if success:
+        print(f"✅ Restored {args.entity_id} from archive")
+    else:
+        print(f"❌ Entity not found in archives: {args.entity_id}", file=sys.stderr)
+        sys.exit(1)
+
+    manager.close()
+
+
+def cmd_archive_list(args: argparse.Namespace) -> None:
+    """List all archive files."""
+    import json
+    from pathlib import Path
+
+    htmlgraph_dir = Path(args.graph_dir).resolve()
+
+    if not htmlgraph_dir.exists():
+        print(f"Error: Directory not found: {htmlgraph_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    archive_dir = htmlgraph_dir / "archives"
+
+    if not archive_dir.exists():
+        print("No archives found")
+        return
+
+    archive_files = sorted(archive_dir.glob("*.html"))
+
+    if args.format == "json":
+        file_list = [
+            {
+                "filename": f.name,
+                "size_kb": f.stat().st_size / 1024,
+                "modified": f.stat().st_mtime,
+            }
+            for f in archive_files
+        ]
+        print(json.dumps({"archives": file_list}, indent=2))
+    else:
+        print(f"\n📦 Archive Files ({len(archive_files)})\n")
+        for f in archive_files:
+            size_kb = f.stat().st_size / 1024
+            print(f"  - {f.name} ({size_kb:.1f} KB)")
+
+
 if __name__ == "__main__":
     main()

htmlgraph/converter.py

@@ -548,6 +548,45 @@ def html_to_session(filepath: Path | str) -> Session:
     # Activity log in HTML is reversed (newest first), so reverse back
     data["activity_log"] = list(reversed(activity_log))
 
+    # Parse detected patterns from table (if present)
+    detected_patterns = []
+    for tr in parser.query("section[data-detected-patterns] table tbody tr"):
+        # Extract pattern data from table row
+        pattern_type = tr.attrs.get("data-pattern-type", "neutral")
+
+        # Extract sequence from first <td class="sequence">
+        seq_td = tr.query_one("td.sequence")
+        sequence_str = seq_td.to_text().strip() if seq_td else ""
+        sequence = [s.strip() for s in sequence_str.split("→")] if sequence_str else []
+
+        # Extract count from third <td>
+        count_td = tr.query_all("td")[2] if len(tr.query_all("td")) > 2 else None
+        count_str = count_td.to_text().strip() if count_td else "0"
+        try:
+            count = int(count_str)
+        except (ValueError, TypeError):
+            count = 0
+
+        # Extract timestamps from fourth <td>
+        time_td = tr.query_all("td")[3] if len(tr.query_all("td")) > 3 else None
+        time_str = time_td.to_text().strip() if time_td else ""
+        times = time_str.split(" / ")
+        first_detected = times[0].strip() if len(times) > 0 else ""
+        last_detected = times[1].strip() if len(times) > 1 else ""
+
+        if sequence:  # Only add if we have a valid sequence
+            detected_patterns.append(
+                {
+                    "sequence": sequence,
+                    "pattern_type": pattern_type,
+                    "detection_count": count,
+                    "first_detected": first_detected,
+                    "last_detected": last_detected,
+                }
+            )
+
+    data["detected_patterns"] = detected_patterns
+
     return Session(**data)
 
 

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