convoviz 0.4.1__py3-none-any.whl

convoviz/interactive.py

@@ -0,0 +1,264 @@
+"""Interactive configuration prompts using questionary."""
+
+import logging
+from pathlib import Path
+from typing import Literal, Protocol, cast
+
+from questionary import Choice, Style, checkbox, select
+from questionary import path as qst_path
+from questionary import text as qst_text
+
+from convoviz.config import ConvovizConfig, OutputKind, get_default_config
+from convoviz.io.loaders import find_latest_zip, validate_zip
+from convoviz.utils import colormaps, default_font_path, font_names, font_path, validate_header
+
+CUSTOM_STYLE = Style(
+    [
+        ("qmark", "fg:#34eb9b bold"),
+        ("question", "bold fg:#e0e0e0"),
+        ("answer", "fg:#34ebeb bold"),
+        ("pointer", "fg:#e834eb bold"),
+        ("highlighted", "fg:#349ceb bold"),
+        ("selected", "fg:#34ebeb"),
+        ("separator", "fg:#eb3434"),
+        ("instruction", "fg:#eb9434"),
+        ("text", "fg:#b2eb34"),
+        ("disabled", "fg:#858585 italic"),
+    ]
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _QuestionaryPrompt[T](Protocol):
+    def ask(self) -> T | None: ...
+
+
+def _ask_or_cancel[T](prompt: _QuestionaryPrompt[T]) -> T:
+    """Ask a questionary prompt; treat Ctrl+C/Ctrl+D as cancelling the run.
+
+    questionary's `.ask()` returns `None` on cancellation (Ctrl+C / Ctrl+D). We
+    convert that to `KeyboardInterrupt` so callers can abort the whole
+    interactive session with a single Ctrl+C.
+    """
+
+    result = prompt.ask()
+    if result is None:
+        raise KeyboardInterrupt
+    return result
+
+
+def _validate_input_path(raw: str) -> bool | str:
+    path = Path(raw)
+    if not path.exists():
+        return "Path must exist"
+
+    if path.is_dir():
+        if (path / "conversations.json").exists():
+            return True
+        return "Directory must contain conversations.json"
+
+    if path.suffix.lower() == ".json":
+        return True
+
+    if path.suffix.lower() == ".zip":
+        return True if validate_zip(path) else "ZIP must contain conversations.json"
+
+    return "Input must be a .zip, a .json, or a directory containing conversations.json"
+
+
+def run_interactive_config(initial_config: ConvovizConfig | None = None) -> ConvovizConfig:
+    """Run interactive prompts to configure convoviz.
+
+    Args:
+        initial_config: Optional starting configuration (uses defaults if None)
+
+    Returns:
+        Updated configuration based on user input
+    """
+    config = initial_config or get_default_config()
+    logger.info("Starting interactive configuration")
+
+    # Set sensible defaults if not already set
+    if not config.input_path:
+        latest = find_latest_zip()
+        if latest:
+            config.input_path = latest
+
+    if not config.wordcloud.font_path:
+        config.wordcloud.font_path = default_font_path()
+
+    # Prompt for input path
+    input_default = str(config.input_path) if config.input_path else ""
+    input_result: str = _ask_or_cancel(
+        qst_path(
+            "Enter the path to the export ZIP, conversations JSON, or extracted directory:",
+            default=input_default,
+            validate=_validate_input_path,
+            style=CUSTOM_STYLE,
+        )
+    )
+
+    if input_result:
+        config.input_path = Path(input_result)
+    logger.debug(f"User selected input: {config.input_path}")
+
+    # Prompt for output folder
+    output_result: str = _ask_or_cancel(
+        qst_path(
+            "Enter the path to the output folder:",
+            default=str(config.output_folder),
+            style=CUSTOM_STYLE,
+        )
+    )
+
+    if output_result:
+        config.output_folder = Path(output_result)
+    logger.debug(f"User selected output: {config.output_folder}")
+
+    # Prompt for outputs to generate
+    output_choices = [
+        Choice(title="Markdown conversations", value=OutputKind.MARKDOWN, checked=True),
+        Choice(title="Graphs (usage analytics)", value=OutputKind.GRAPHS, checked=True),
+        Choice(title="Word clouds", value=OutputKind.WORDCLOUDS, checked=True),
+    ]
+
+    selected_outputs: list[OutputKind] = _ask_or_cancel(
+        checkbox(
+            "Select outputs to generate:",
+            choices=output_choices,
+            style=CUSTOM_STYLE,
+        )
+    )
+
+    config.outputs = set(selected_outputs) if selected_outputs else set()
+    logger.debug(f"User selected outputs: {config.outputs}")
+
+    # Prompt for markdown settings (only if markdown output is selected)
+    if OutputKind.MARKDOWN in config.outputs:
+        # Prompt for author headers
+        headers = config.message.author_headers
+        for role in ["user", "assistant"]:
+            current = getattr(headers, role)
+            result: str = _ask_or_cancel(
+                qst_text(
+                    f"Enter the message header for '{role}':",
+                    default=current,
+                    validate=lambda t: validate_header(t)
+                    or "Must be a valid markdown header (e.g., # Title)",
+                    style=CUSTOM_STYLE,
+                )
+            )
+            if result:
+                setattr(headers, role, result)
+        logger.debug(f"User selected headers: {headers}")
+
+        # Prompt for markdown flavor
+        flavor_result = cast(
+            Literal["standard", "obsidian"],
+            _ask_or_cancel(
+                select(
+                    "Select the markdown flavor:",
+                    choices=["standard", "obsidian"],
+                    default=config.conversation.markdown.flavor,
+                    style=CUSTOM_STYLE,
+                )
+            ),
+        )
+
+        if flavor_result:
+            config.conversation.markdown.flavor = flavor_result
+        logger.debug(f"User selected flavor: {config.conversation.markdown.flavor}")
+
+        # Prompt for YAML headers
+        yaml_config = config.conversation.yaml
+        yaml_choices = [
+            Choice(title=field, checked=getattr(yaml_config, field))
+            for field in [
+                "title",
+                "tags",
+                "chat_link",
+                "create_time",
+                "update_time",
+                "model",
+                "used_plugins",
+                "message_count",
+                "content_types",
+                "custom_instructions",
+            ]
+        ]
+
+        selected: list[str] = _ask_or_cancel(
+            checkbox(
+                "Select YAML metadata headers to include:",
+                choices=yaml_choices,
+                style=CUSTOM_STYLE,
+            )
+        )
+
+        selected_set = set(selected)
+        for field_name in [
+            "title",
+            "tags",
+            "chat_link",
+            "create_time",
+            "update_time",
+            "model",
+            "used_plugins",
+            "message_count",
+            "content_types",
+            "custom_instructions",
+        ]:
+            setattr(yaml_config, field_name, field_name in selected_set)
+
+    # Prompt for wordcloud settings (only if wordclouds output is selected)
+    if OutputKind.WORDCLOUDS in config.outputs:
+        # Prompt for font
+        available_fonts = font_names()
+        if available_fonts:
+            current_font = (
+                config.wordcloud.font_path.stem
+                if config.wordcloud.font_path
+                else available_fonts[0]
+            )
+            font_result: str = _ask_or_cancel(
+                select(
+                    "Select the font for word clouds:",
+                    choices=available_fonts,
+                    default=current_font if current_font in available_fonts else available_fonts[0],
+                    style=CUSTOM_STYLE,
+                )
+            )
+
+            if font_result:
+                config.wordcloud.font_path = font_path(font_result)
+
+        # Prompt for colormap
+        available_colormaps = colormaps()
+        if available_colormaps:
+            colormap_result: str = _ask_or_cancel(
+                select(
+                    "Select the color theme for word clouds:",
+                    choices=available_colormaps,
+                    default=config.wordcloud.colormap
+                    if config.wordcloud.colormap in available_colormaps
+                    else available_colormaps[0],
+                    style=CUSTOM_STYLE,
+                )
+            )
+
+            if colormap_result:
+                config.wordcloud.colormap = colormap_result
+
+        # Prompt for custom stopwords
+        stopwords_result: str = _ask_or_cancel(
+            qst_text(
+                "Enter custom stopwords (comma-separated):",
+                default=config.wordcloud.custom_stopwords,
+                style=CUSTOM_STYLE,
+            )
+        )
+
+        config.wordcloud.custom_stopwords = stopwords_result
+
+    return config

convoviz/io/__init__.py

@@ -0,0 +1,21 @@
+"""I/O operations for convoviz."""
+
+from convoviz.io.loaders import (
+    load_collection_from_json,
+    load_collection_from_zip,
+    load_conversation_from_json,
+)
+from convoviz.io.writers import (
+    save_collection,
+    save_conversation,
+    save_custom_instructions,
+)
+
+__all__ = [
+    "load_collection_from_json",
+    "load_collection_from_zip",
+    "load_conversation_from_json",
+    "save_collection",
+    "save_conversation",
+    "save_custom_instructions",
+]

convoviz/io/assets.py

@@ -0,0 +1,109 @@
+"Asset management functions."
+
+import logging
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
+    """Find the actual file for a given asset ID in the source directory.
+
+    Args:
+        source_dir: Directory to search in
+        asset_id: The asset ID (e.g., "file-uuid")
+
+    Returns:
+        Path to the found file, or None
+    """
+    if not source_dir.exists():
+        return None
+
+    source_dir = source_dir.resolve()
+
+    # Safety check for asset_id
+    if ".." in asset_id or "/" in asset_id or "\\" in asset_id:
+        return None
+
+    # 1. Try exact match
+    exact_path = (source_dir / asset_id).resolve()
+    if exact_path.exists() and exact_path.is_file() and exact_path.is_relative_to(source_dir):
+        logger.debug(f"Resolved asset (exact): {asset_id} -> {exact_path}")
+        return exact_path
+
+    # 2. Try prefix match in root
+    try:
+        candidates = list(source_dir.glob(f"{asset_id}*"))
+        files = [
+            p.resolve()
+            for p in candidates
+            if p.is_file() and p.resolve().is_relative_to(source_dir)
+        ]
+        if files:
+            logger.debug(f"Resolved asset (prefix root): {asset_id} -> {files[0]}")
+            return files[0]
+    except Exception:
+        pass
+
+    # 3. Try prefix match in dalle-generations
+    dalle_dir = source_dir / "dalle-generations"
+    if dalle_dir.exists() and dalle_dir.is_dir():
+        dalle_dir = dalle_dir.resolve()
+        try:
+            candidates = list(dalle_dir.glob(f"{asset_id}*"))
+            files = [
+                p.resolve()
+                for p in candidates
+                if p.is_file() and p.resolve().is_relative_to(dalle_dir)
+            ]
+            if files:
+                logger.debug(f"Resolved asset (dalle): {asset_id} -> {files[0]}")
+                return files[0]
+        except Exception:
+            pass
+
+    # 4. Try prefix match in user-* directories (new 2025 format)
+    try:
+        for user_dir in source_dir.glob("user-*"):
+            if user_dir.is_dir():
+                user_dir = user_dir.resolve()
+                candidates = list(user_dir.glob(f"{asset_id}*"))
+                files = [
+                    p.resolve()
+                    for p in candidates
+                    if p.is_file() and p.resolve().is_relative_to(user_dir)
+                ]
+                if files:
+                    logger.debug(f"Resolved asset (user dir): {asset_id} -> {files[0]}")
+                    return files[0]
+    except Exception:
+        pass
+
+    return None
+
+
+def copy_asset(source_path: Path, dest_dir: Path) -> str:
+    """Copy an asset to the destination directory.
+
+    Args:
+        source_path: The source file path
+        dest_dir: The root output directory (assets will be in dest_dir/assets)
+
+    Returns:
+        Relative path to the asset (e.g., "assets/image.png")
+    """
+    assets_dir = dest_dir / "assets"
+    assets_dir.mkdir(parents=True, exist_ok=True)
+
+    dest_path = assets_dir / source_path.name
+
+    if not dest_path.exists():
+        try:
+            shutil.copy2(source_path, dest_path)
+            logger.debug(f"Copied asset: {source_path.name}")
+        except Exception as e:
+            logger.warning(f"Failed to copy asset {source_path}: {e}")
+
+    # Return forward-slash path for Markdown compatibility even on Windows
+    return f"assets/{source_path.name}"

convoviz/io/loaders.py

@@ -0,0 +1,191 @@
+"""Loading functions for conversations and collections."""
+
+import logging
+from pathlib import Path, PurePosixPath
+from zipfile import ZipFile
+
+from orjson import loads
+
+from convoviz.exceptions import InvalidZipError
+from convoviz.models import Conversation, ConversationCollection
+
+logger = logging.getLogger(__name__)
+
+
+def _is_safe_zip_member_name(name: str) -> bool:
+    """Return True if a ZIP entry name is safe to extract.
+
+    This is intentionally OS-agnostic: it treats both ``/`` and ``\\`` as path
+    separators and rejects absolute paths, drive-letter paths, and ``..`` parts.
+    """
+    normalized = name.replace("\\", "/")
+    member_path = PurePosixPath(normalized)
+
+    # Absolute paths (e.g. "/etc/passwd") or empty names
+    if not normalized or member_path.is_absolute():
+        return False
+
+    # Windows drive letters / UNC-style prefixes stored in the archive
+    first = member_path.parts[0] if member_path.parts else ""
+    if first.endswith(":") or first.startswith("//") or first.startswith("\\\\"):
+        return False
+
+    return ".." not in member_path.parts
+
+
+def extract_archive(filepath: Path) -> Path:
+    """Extract a ZIP file and return the extraction folder path.
+
+    Includes safety checks to prevent Path Traversal (Zip-Slip).
+
+    Args:
+        filepath: Path to the ZIP file
+
+    Returns:
+        Path to the extracted folder
+
+    Raises:
+        InvalidZipError: If extraction fails or a security risk is detected
+    """
+    folder = filepath.with_suffix("")
+    folder.mkdir(parents=True, exist_ok=True)
+    logger.info(f"Extracting archive: {filepath} to {folder}")
+
+    with ZipFile(filepath) as zf:
+        for member in zf.infolist():
+            # Check for path traversal (Zip-Slip) in an OS-agnostic way.
+            # ZIP files are typically POSIX-path-like, but malicious archives can
+            # embed backslashes or drive-letter tricks.
+            if not _is_safe_zip_member_name(member.filename):
+                raise InvalidZipError(
+                    str(filepath), reason=f"Malicious path in ZIP: {member.filename}"
+                )
+
+            # Additional check using resolved paths
+            normalized = member.filename.replace("\\", "/")
+            target_path = (folder / normalized).resolve()
+            if not target_path.is_relative_to(folder.resolve()):
+                raise InvalidZipError(
+                    str(filepath), reason=f"Malicious path in ZIP: {member.filename}"
+                )
+
+        zf.extractall(folder)
+    return folder
+
+
+def validate_zip(filepath: Path) -> bool:
+    """Check if a ZIP file contains conversations.json.
+
+    Args:
+        filepath: Path to the ZIP file
+
+    Returns:
+        True if valid, False otherwise
+    """
+    if not filepath.is_file() or filepath.suffix != ".zip":
+        return False
+    try:
+        with ZipFile(filepath) as zf:
+            return "conversations.json" in zf.namelist()
+    except Exception:
+        return False
+
+
+def load_conversation_from_json(filepath: Path | str) -> Conversation:
+    """Load a single conversation from a JSON file.
+
+    Args:
+        filepath: Path to the JSON file
+
+    Returns:
+        Loaded Conversation object
+    """
+    filepath = Path(filepath)
+    with filepath.open(encoding="utf-8") as f:
+        data = loads(f.read())
+    return Conversation(**data)
+
+
+def load_collection_from_json(filepath: Path | str) -> ConversationCollection:
+    """Load a conversation collection from a JSON file.
+
+    The JSON file should contain an array of conversation objects,
+    or an object with a "conversations" key.
+
+    Args:
+        filepath: Path to the JSON file
+
+    Returns:
+        Loaded ConversationCollection object
+    """
+    filepath = Path(filepath)
+    logger.debug(f"Loading collection from JSON: {filepath}")
+    with filepath.open(encoding="utf-8") as f:
+        data = loads(f.read())
+
+    # Handle case where export is wrapped in a top-level object
+    if isinstance(data, dict) and "conversations" in data:
+        data = data["conversations"]
+
+    return ConversationCollection(conversations=data, source_path=filepath.parent)
+
+
+def load_collection_from_zip(filepath: Path | str) -> ConversationCollection:
+    """Load a conversation collection from a ChatGPT export ZIP file.
+
+    Args:
+        filepath: Path to the ZIP file
+
+    Returns:
+        Loaded ConversationCollection object
+
+    Raises:
+        InvalidZipError: If the ZIP file is invalid or missing conversations.json
+    """
+    filepath = Path(filepath)
+
+    if not validate_zip(filepath):
+        raise InvalidZipError(str(filepath))
+
+    extracted_folder = extract_archive(filepath)
+    conversations_path = extracted_folder / "conversations.json"
+
+    return load_collection_from_json(conversations_path)
+
+
+def find_latest_zip(directory: Path | None = None) -> Path | None:
+    """Find the most recently created ZIP file in a directory.
+
+    Args:
+        directory: Directory to search (defaults to ~/Downloads)
+
+    Returns:
+        Path to the most recent ZIP, or None if none found
+    """
+    if directory is None:
+        directory = Path.home() / "Downloads"
+
+    zip_files = list(directory.glob("*.zip"))
+    if not zip_files:
+        return None
+
+    return max(zip_files, key=lambda p: p.stat().st_ctime)
+
+
+def find_latest_bookmarklet_json(directory: Path | None = None) -> Path | None:
+    """Find the most recent bookmarklet JSON file in a directory.
+
+    Args:
+        directory: Directory to search (defaults to ~/Downloads)
+
+    Returns:
+        Path to the most recent bookmarklet JSON, or None if none found
+    """
+    if directory is None:
+        directory = Path.home() / "Downloads"
+
+    bookmarklet_files = [f for f in directory.glob("*.json") if "bookmarklet" in f.name.lower()]
+    if not bookmarklet_files:
+        return None
+
+    return max(bookmarklet_files, key=lambda p: p.stat().st_ctime)