thread-archive 0.0.2__py3-none-any.whl

thread_archive/_thread_import/schemas/cursor/v1.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "cursor_export_v1",
+  "title": "Cursor Export v1",
+  "description": "Cursor IDE chat export format (from cursor_export tool)",
+  "type": "object",
+  "properties": {
+    "provider": {
+      "type": "string",
+      "const": "cursor"
+    },
+    "export_version": {
+      "type": "string"
+    },
+    "export_date": {
+      "type": "string",
+      "description": "ISO timestamp"
+    },
+    "conversations": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/conversation"
+      }
+    }
+  },
+  "definitions": {
+    "conversation": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Conversation ID"
+        },
+        "title": {
+          "type": ["string", "null"],
+          "description": "Chat title"
+        },
+        "workspace_hash": {
+          "type": "string",
+          "description": "Hash identifying the workspace"
+        },
+        "workspace_name": {
+          "type": ["string", "null"],
+          "description": "Human-readable workspace name"
+        },
+        "workspace_uri": {
+          "type": ["string", "null"],
+          "description": "Path to the workspace"
+        },
+        "messages": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/message"
+          }
+        },
+        "bubbles": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/bubble"
+          },
+          "description": "Alternative message format (raw Cursor format)"
+        }
+      }
+    },
+    "message": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Message ID"
+        },
+        "role": {
+          "type": "string",
+          "enum": ["user", "assistant", "system", "tool"],
+          "description": "Message author role"
+        },
+        "content": {
+          "type": ["string", "null"],
+          "description": "Message text content"
+        },
+        "content_blocks": {
+          "type": "array",
+          "description": "Pre-parsed content blocks"
+        },
+        "created_at": {
+          "type": ["string", "null"],
+          "description": "ISO timestamp"
+        },
+        "tool_calls": {
+          "type": "array",
+          "description": "Tool/function calls made"
+        },
+        "tool_results": {
+          "type": "array",
+          "description": "Results from tool calls"
+        },
+        "model": {
+          "type": ["string", "null"],
+          "description": "Model used for response"
+        }
+      }
+    },
+    "bubble": {
+      "type": "object",
+      "description": "Raw Cursor bubble format",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["user", "ai"],
+          "description": "Bubble type"
+        },
+        "text": {
+          "type": ["string", "null"],
+          "description": "Message text"
+        },
+        "rawText": {
+          "type": ["string", "null"],
+          "description": "Raw text before processing"
+        },
+        "codeBlocks": {
+          "type": "array",
+          "description": "Code blocks in the message"
+        },
+        "selections": {
+          "type": "array",
+          "description": "Code selections referenced"
+        },
+        "messageId": {
+          "type": ["string", "integer"],
+          "description": "Message identifier"
+        },
+        "relevantFiles": {
+          "type": "array",
+          "description": "Files relevant to this message"
+        },
+        "capabilityStatuses": {
+          "type": "array"
+        }
+      }
+    }
+  }
+}

thread_archive/_thread_import/schemas/cursor/v2.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "cursor_export_v2",
+  "title": "Cursor Export v2",
+  "description": "Cursor IDE chat export format with toolFormerData (newer Cursor versions)",
+  "type": "object",
+  "properties": {
+    "provider": {
+      "type": "string",
+      "const": "cursor"
+    },
+    "export_version": {
+      "type": "string"
+    },
+    "export_date": {
+      "type": "string",
+      "description": "ISO timestamp"
+    },
+    "conversations": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/conversation"
+      }
+    }
+  },
+  "definitions": {
+    "conversation": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Conversation ID"
+        },
+        "title": {
+          "type": ["string", "null"],
+          "description": "Chat title"
+        },
+        "workspace_hash": {
+          "type": "string",
+          "description": "Hash identifying the workspace"
+        },
+        "workspace_name": {
+          "type": ["string", "null"],
+          "description": "Human-readable workspace name"
+        },
+        "workspace_uri": {
+          "type": ["string", "null"],
+          "description": "Path to the workspace"
+        },
+        "messages": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/message"
+          }
+        },
+        "bubbles": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/bubble"
+          },
+          "description": "Alternative message format (raw Cursor format)"
+        }
+      }
+    },
+    "message": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Message ID"
+        },
+        "role": {
+          "type": "string",
+          "enum": ["user", "assistant", "system", "tool"],
+          "description": "Message author role"
+        },
+        "content": {
+          "type": ["string", "null"],
+          "description": "Message text content"
+        },
+        "content_blocks": {
+          "type": "array",
+          "description": "Pre-parsed content blocks"
+        },
+        "created_at": {
+          "type": ["string", "null"],
+          "description": "ISO timestamp"
+        },
+        "tool_calls": {
+          "type": "array",
+          "description": "Tool/function calls made"
+        },
+        "tool_results": {
+          "type": "array",
+          "description": "Results from tool calls"
+        },
+        "model": {
+          "type": ["string", "null"],
+          "description": "Model used for response"
+        },
+        "tool_call": {
+          "$ref": "#/definitions/toolCall",
+          "description": "v2: Structured tool call from toolFormerData"
+        },
+        "thinking": {
+          "$ref": "#/definitions/thinking",
+          "description": "v2: Thinking/reasoning content"
+        }
+      }
+    },
+    "bubble": {
+      "type": "object",
+      "description": "Raw Cursor bubble format with v2 toolFormerData",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["user", "ai"],
+          "description": "Bubble type"
+        },
+        "text": {
+          "type": ["string", "null"],
+          "description": "Message text"
+        },
+        "rawText": {
+          "type": ["string", "null"],
+          "description": "Raw text before processing"
+        },
+        "codeBlocks": {
+          "type": "array",
+          "description": "Code blocks in the message"
+        },
+        "selections": {
+          "type": "array",
+          "description": "Code selections referenced"
+        },
+        "messageId": {
+          "type": ["string", "integer"],
+          "description": "Message identifier"
+        },
+        "relevantFiles": {
+          "type": "array",
+          "description": "Files relevant to this message"
+        },
+        "capabilityStatuses": {
+          "type": "array"
+        },
+        "toolFormerData": {
+          "$ref": "#/definitions/toolFormerData",
+          "description": "v2: Tool calling data from newer Cursor versions"
+        }
+      }
+    },
+    "toolFormerData": {
+      "type": "object",
+      "description": "Tool calling data structure (v2 indicator)",
+      "properties": {
+        "toolCalls": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/toolCall"
+          }
+        },
+        "toolResults": {
+          "type": "array"
+        }
+      }
+    },
+    "toolCall": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Tool name"
+        },
+        "arguments": {
+          "type": ["string", "object"],
+          "description": "Tool arguments (JSON string or object)"
+        },
+        "id": {
+          "type": "string",
+          "description": "Tool call ID"
+        }
+      }
+    },
+    "thinking": {
+      "type": "object",
+      "description": "Thinking/reasoning block",
+      "properties": {
+        "text": {
+          "type": "string"
+        },
+        "thinking_duration_ms": {
+          "type": "number",
+          "description": "v2 indicator: duration of thinking"
+        }
+      }
+    }
+  }
+}

thread_archive/_thread_import/timestamps.py

@@ -0,0 +1,57 @@
+"""Unified timestamp parsing for thread import.
+
+Handles ISO 8601 strings (with or without Z suffix), unix epoch
+(seconds or milliseconds), and None/empty values.
+"""
+
+from datetime import datetime, timezone
+from typing import Optional, Union
+
+
+def parse_timestamp(ts: Optional[Union[str, int, float]], *, default: Optional[datetime] = None) -> Optional[datetime]:
+    """Parse a timestamp value into a datetime.
+
+    Args:
+        ts: ISO string, unix epoch (seconds or milliseconds), or None
+        default: fallback value when ts is None/empty/unparseable.
+                 If not provided, returns None on failure.
+
+    Returns:
+        Parsed datetime, or default if parsing fails.
+    """
+    if ts is None or ts == "":
+        return default
+
+    # ISO string
+    if isinstance(ts, str):
+        try:
+            if ts.endswith("Z"):
+                ts = ts[:-1] + "+00:00"
+            dt = datetime.fromisoformat(ts)
+        except (ValueError, TypeError):
+            return default
+        # An offset-less ISO string parses to a naive datetime; treat it as UTC
+        # so callers never mix naive and aware datetimes (comparing the two
+        # raises TypeError in the event-ordering path). Explicit offsets are kept.
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+
+    # Unix timestamp (seconds or milliseconds). Epoch is an absolute instant —
+    # build an aware UTC datetime, not a naive-local one (the host's local zone
+    # would silently skew the time by the UTC offset).
+    if isinstance(ts, (int, float)):
+        try:
+            if ts > 1_000_000_000_000:
+                ts = ts / 1000
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
+        except (ValueError, OSError):
+            return default
+
+    return default
+
+
+def parse_timestamp_iso(ts: Optional[Union[str, int, float]]) -> Optional[str]:
+    """Parse a timestamp and return as ISO string, or None."""
+    dt = parse_timestamp(ts)
+    return dt.isoformat() if dt else None

thread_archive/_thread_import/tool_names.py

@@ -0,0 +1,48 @@
+"""Canonical tool name mapping from provider-specific names to Thread's standard names.
+
+Thread uses Claude Code's tool names as the canonical standard (Edit, Write, Read, Bash, etc.)
+since those are the de facto standard in the database. Provider-specific names (edit_file_v2,
+run_terminal_cmd, etc.) are mapped to these canonical names during import.
+
+The original provider name is preserved as `provider_tool_name` on content blocks and events.
+"""
+
+# Provider tool name → Thread canonical name
+TOOL_NAME_MAP: dict[str, str] = {
+    # Cursor file tools
+    "edit_file_v2": "Edit",
+    "edit_file": "Edit",
+    "write_file": "Write",
+    "read_file": "Read",
+    "read_file_v2": "Read",
+    # Cursor terminal tools
+    "run_terminal_cmd": "Bash",
+    "run_terminal_command_v2": "Bash",
+    # Cursor search/navigation tools
+    "list_dir": "Glob",
+    "list_dir_v2": "Glob",
+    "search_files": "Grep",
+    "codebase_search": "Grep",
+    "grep_search": "Grep",
+}
+
+# Canonical tool names that operate on files — normalized events MUST have input.file_path
+FILE_TOOLS: frozenset[str] = frozenset({"Edit", "Write", "Read"})
+
+# Provider-specific field name that holds the file path in the tool's input dict.
+# None means the input doesn't contain the path at all (must recover from code_blocks).
+PROVIDER_PATH_FIELDS: dict[str, str | None] = {
+    "read_file_v2": "path",
+    "read_file": "path",
+    "edit_file": None,
+    "edit_file_v2": None,
+    "write_file": "filePath",
+}
+
+
+def normalize_tool_name(name: str) -> str:
+    """Map a provider tool name to Thread's canonical name.
+
+    Returns the original name unchanged if no mapping exists.
+    """
+    return TOOL_NAME_MAP.get(name, name)

thread_archive/_truth/__init__.py

@@ -0,0 +1,40 @@
+"""JSONL truth-log: durable source of truth, with reindex as the recovery primitive.
+
+JSONL is truth; ``index.db`` is a rebuildable projection. See :mod:`.jsonl_log`.
+"""
+
+from __future__ import annotations
+
+from .jsonl_log import (
+    append_event_row,
+    append_kg_event,
+    checkpoint,
+    log_dir,
+    rebuild_truth_from_store,
+    record_thread,
+    reindex,
+    reset_handles,
+    scan_truth_counts,
+    shared_ingest_lock,
+    try_shared_ingest_lock,
+    unstage_thread,
+    write_events,
+)
+from .repair import repair_truth
+
+__all__ = [
+    "write_events",
+    "append_event_row",
+    "append_kg_event",
+    "record_thread",
+    "unstage_thread",
+    "checkpoint",
+    "reindex",
+    "rebuild_truth_from_store",
+    "log_dir",
+    "repair_truth",
+    "reset_handles",
+    "scan_truth_counts",
+    "shared_ingest_lock",
+    "try_shared_ingest_lock",
+]