byterover-cli 0.2.1 → 0.3.1

package/dist/infra/parsers/raw/raw-cursor-service.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Cursor IDE Raw Service
+ * Consolidates CursorParser + CursorRawParser + Enhanced Bubble Extraction
+ * Parses Cursor IDE chat sessions from local storage and workspace data
+ */
+import { Agent } from '../../../core/domain/entities/agent.js';
+import { IRawParserService } from '../../../core/interfaces/parser/i-raw-parser-service.js';
+/**
+ * Cursor Raw Service
+ * Handles extraction of Cursor sessions from both exported files and raw storage
+ *
+ * Method Organization:
+ * - Constructor
+ * - Public Methods: parse(), parseFromDirectory()
+ * - Private Workspace Methods: loadWorkspaceComposers(), extractChatIdFromCodeBlockDiffKey()
+ * - Private Helper Methods (Bubble Extraction): createEnhancedBubble(), and extraction methods
+ * - Private Utility Methods: safeParseJSON()
+ */
+export declare class CursorRawService implements IRawParserService {
+    private ide;
+    /**
+     * Initialize Cursor Raw Service
+     *
+     * @param ide - The IDE type (Cursor)
+     */
+    constructor(ide: Agent);
+    /**
+     * Main entry point - Parse Cursor IDE sessions from a custom directory
+     *
+     * Parses Cursor IDE chat sessions from workspace storage and exports to JSON files.
+     * Handles extraction from database files and raw workspace data structures.
+     *
+     * @param customDir - Path to directory containing Cursor session data
+     * @param outputDir - Optional output directory (defaults to process.cwd()/.brv/logs/{ide}/raw)
+     * @returns Promise resolving to true if parsing succeeded, false otherwise
+     */
+    parse(customDir: string, outputDir?: string): Promise<boolean>;
+    /**
+     * Parse Cursor IDE sessions from a workspace directory
+     *
+     * Handles extraction of chat sessions from Cursor's database and storage structures.
+     * Processes bubbles, composer data, and other session metadata to create normalized
+     * session files. Exports results to workspace-specific output directory.
+     *
+     * @param customDir - Path to workspace directory containing Cursor session data
+     * @param outputDir - Optional output directory (defaults to process.cwd()/.brv/logs/{ide}/raw)
+     * @returns Promise resolving to true if parsing succeeded, false otherwise
+     */
+    parseFromDirectory(customDir: string, outputDir?: string): Promise<boolean>;
+    /**
+     * Create an enhanced chat bubble with all extracted metadata and context
+     *
+     * Consolidates raw Cursor bubble data with associated tool results, console logs,
+     * context information, code diffs, file checkpoints, and code blocks into a single
+     * enhanced bubble structure. Extracts optional data from maps if available.
+     *
+     * @param type - Message type: 'ai' for assistant messages or 'user' for user messages
+     * @param text - Raw message text content from the bubble
+     * @param timestamp - Unix timestamp in milliseconds when the bubble was created
+     * @param bubble - Raw Cursor bubble object containing base message data
+     * @param bubbleId - Unique identifier for this bubble, used to look up associated data
+     * @param messageContextMap - Optional map of bubble IDs to RawCursorMessageRequestContext arrays
+     * @param codeBlockDiffMap - Optional map of bubble IDs to RawCursorCodeDiff arrays
+     * @param checkpointMap - Optional map of bubble IDs to RawCursorFileCheckpoint data
+     * @returns Enhanced bubble with all extracted metadata and context information
+     */
+    private createEnhancedBubble;
+    /**
+     * Export parsed conversations to JSON files in workspace-specific output directory
+     *
+     * Writes each conversation to a separate JSON file named by composer ID, containing
+     * bubbles, metadata (id, timestamp, title), workspace hash, and workspace paths.
+     * Logs file sizes in KB and exports all conversations with structured formatting.
+     *
+     * @param allConversations - Array of conversation objects with bubbles and metadata
+     * @param workspaceDir - Path to workspace directory for output files
+     * @param workspaceHash - Unique hash identifier for the workspace
+     * @param _outputDir - Root output directory (used for logging reference)
+     */
+    private exportConversations;
+    /**
+     * Extract the composer ID from a code block diff database key
+     *
+     * Parses the database key pattern "codeBlockDiff:chatId:diffId" to extract
+     * the chat/composer ID using regex pattern matching. Returns null if key format
+     * doesn't match expected pattern.
+     *
+     * @param key - Database key string in format "codeBlockDiff:chatId:diffId"
+     * @returns The extracted composer/chat ID, or null if pattern doesn't match
+     */
+    private extractChatIdFromCodeBlockDiffKey;
+    /**
+     * Extract code blocks from a Cursor bubble's codeBlocks object
+     *
+     * Retrieves the code blocks map from a bubble if it exists and is non-empty.
+     * Code blocks are stored as key-value pairs where keys are block IDs and values
+     * are the code content strings. Returns undefined if bubble has no code blocks,
+     * codeBlocks property is not an object, or the object is empty.
+     *
+     * @param bubble - The raw Cursor bubble object to extract code blocks from
+     * @returns Object mapping code block IDs to code content strings, or undefined if none exist
+     */
+    private extractCodeBlocks;
+    /**
+     * Extract code diffs associated with a specific bubble from the code block diff map
+     *
+     * Looks up code diffs for the given bubble ID in the codeBlockDiffMap. Code diffs
+     * represent changes made to files during the conversation, containing both the original
+     * and new versions relative to a base version (v0). Returns undefined if the map is
+     * unavailable, the bubble has no associated diffs, or the diffs array is empty.
+     * Normalizes diff objects to ensure all required fields (diffId, filePath,
+     * newModelDiffWrtV0, originalModelDiffWrtV0) are present, using empty string for missing diffId.
+     *
+     * @param bubbleId - Unique identifier of the bubble to look up diffs for
+     * @param codeBlockDiffMap - Optional map of bubble IDs to RawCursorCodeDiff arrays
+     * @returns Array of normalized RawCursorCodeDiff objects with all required fields, or undefined if none exist
+     */
+    private extractCodeDiffs;
+    /**
+     * Extract console logs from a Cursor bubble's consoleLogs array
+     *
+     * Retrieves the console logs array from a bubble if it exists and contains entries.
+     * Console logs capture terminal or debug output associated with a conversation turn.
+     * Returns undefined if the bubble has no console logs, consoleLogs property is not an array,
+     * or the array is empty. Used to preserve terminal/console output context in enhanced bubbles.
+     *
+     * @param bubble - The raw Cursor bubble object to extract console logs from
+     * @returns Array of console log strings, or undefined if none exist
+     */
+    private extractConsoleLogs;
+    /**
+     * Extract and consolidate context information from bubble and message context map
+     *
+     * Consolidates context data from two sources to create a comprehensive view of the
+     * conversation context:
+     * 1. Direct bubble properties: attachedFoldersListDirResults, cursorRules
+     * 2. Message context map data: gitStatus, knowledgeItems, todos, deletedFiles, terminalFiles
+     *
+     * When both sources provide the same field, preference is given to the message context map
+     * data as it tends to be more complete. Returns undefined if no context data is found from
+     * either source. The consolidated context helps understand the environment and state during
+     * the conversation turn.
+     *
+     * @param bubble - The raw Cursor bubble object with inline context data
+     * @param messageContextMap - Optional map of bubble IDs to RawCursorMessageRequestContext arrays
+     * @param bubbleId - Optional bubble ID to look up context in messageContextMap
+     * @returns RawCursorContextInfo object with consolidated context data, or undefined if no data found
+     */
+    private extractContextInfo;
+    /**
+     * Extract file checkpoint state associated with a bubble from the checkpoint map
+     *
+     * Looks up the file checkpoint for a given bubble ID in the checkpoint map. File checkpoints
+     * capture the state of the file system at a particular conversation turn, including which files
+     * existed, were newly created, or were non-existent, as well as active inline diff information.
+     * Returns undefined if the map is unavailable or the bubble has no associated checkpoint.
+     *
+     * Normalizes the checkpoint object to ensure all array fields (files, newlyCreatedFolders,
+     * nonExistentFiles, activeInlineDiffs) are present, using empty arrays as defaults if not found.
+     * This normalization ensures consistent structure for downstream processing. The checkpointId
+     * field is intentionally excluded from the returned object.
+     *
+     * @param bubbleId - Unique identifier of the bubble to look up checkpoint for
+     * @param checkpointMap - Optional map of bubble IDs to RawCursorFileCheckpoint objects with checkpointId
+     * @returns Normalized RawCursorFileCheckpoint object with all required array fields, or undefined if none exists
+     */
+    private extractFileCheckpoint;
+    /**
+     * Extract tool execution results from a bubble's toolFormerData object
+     *
+     * Parses tool execution metadata from the bubble, including tool name, status,
+     * parameters, results, and additional context. Returns undefined if bubble has no
+     * toolFormerData or is missing required fields (name, status). Safely parses JSON
+     * strings for params, rawArgs, and result fields that may contain serialized data.
+     *
+     * @param bubble - The raw Cursor bubble object containing tool execution data
+     * @returns RawCursorToolResult object with execution details, or undefined if no valid tool data
+     */
+    private extractToolResults;
+    /**
+     * Load all bubbles from the database and build indexed maps
+     *
+     * Queries the database for all bubble entries matching the bubble ID pattern,
+     * parses JSON values, and builds maps for fast lookups. Creates bubble-to-workspace
+     * mapping and tracks unique workspace hashes. Skips invalid or unparseable entries.
+     *
+     * @param db - Better-sqlite3 database instance with cursorDiskKV table
+     * @returns Object containing: bubbleMap (ID -> bubble), bubbleWorkspaceMap (ID -> workspace hash), uniqueWorkspaces set
+     */
+    private loadBubbles;
+    /**
+     * Load all file checkpoints from the database and build indexed map
+     *
+     * Queries the database for all checkpoint entries matching the checkpoint ID pattern,
+     * parses JSON values, and builds a map for fast lookups. Handles multiple checkpoints
+     * per composer by keeping the latest based on checkpoint ID string comparison.
+     * Skips invalid or unparseable entries.
+     *
+     * @param db - Better-sqlite3 database instance with cursorDiskKV table
+     * @returns Map of composer IDs to their RawCursorFileCheckpoint objects with checkpointId field
+     */
+    private loadCheckpoints;
+    /**
+     * Load all code block diffs from the database and build indexed map
+     *
+     * Queries the database for all code block diff entries, extracts chat/composer IDs
+     * from keys, parses JSON values, and groups diffs by composer ID. Each diff includes
+     * the diffId extracted from the database key. Skips invalid or unparseable entries.
+     *
+     * @param db - Better-sqlite3 database instance with cursorDiskKV table
+     * @returns Map of composer IDs to arrays of RawCursorCodeDiff objects with diffId field
+     */
+    private loadCodeBlockDiffs;
+    /**
+     * Load all message request context from the database and build indexed map
+     *
+     * Queries the database for all message request context entries, parses JSON values,
+     * and groups contexts by composer ID. Extracts context ID from key parts or uses
+     * default context ID if not present. Skips invalid or unparseable entries and keys
+     * with insufficient format.
+     *
+     * @param db - Better-sqlite3 database instance with cursorDiskKV table
+     * @returns Map of composer IDs to arrays of RawCursorMessageRequestContext objects with contextId field
+     */
+    private loadMessageContext;
+    /**
+     * Load composer IDs that are specific to a workspace
+     *
+     * Reads the workspace's state.vscdb database, extracts composer data from the
+     * ItemTable, and builds a set of composer IDs that belong to this workspace.
+     * Returns empty set if database or composer data is not found. Logs warnings
+     * if database or data is unavailable.
+     *
+     * @param workspacePath - Path to the workspace directory containing state.vscdb
+     * @returns Set of composer IDs that belong to this workspace
+     */
+    private loadWorkspaceComposers;
+    /**
+     * Log parsing statistics for processed conversations
+     *
+     * Outputs summary information about conversation parsing results, including both successful
+     * parses and various skip conditions. Helps users understand why certain conversations were
+     * not included in the output. The function displays:
+     * - Total successfully parsed conversations
+     * - Conversations skipped because they don't belong to this workspace
+     * - Conversations skipped due to having no extractable bubbles (empty conversations)
+     * - Conversations skipped due to missing conversation headers (malformed data)
+     *
+     * Omits zero-count skip reasons from output for cleaner, more focused logging that only
+     * shows relevant information.
+     *
+     * @param parsed - Number of successfully parsed conversations
+     * @param skippedNotInWorkspace - Number of conversations skipped (not in this workspace)
+     * @param skippedNoBubbles - Number of conversations skipped (no extractable bubbles)
+     * @param skippedNoHeaders - Number of conversations skipped (no conversation headers)
+     */
+    private logConversationStats;
+    /**
+     * Process conversation headers and create enhanced bubbles from raw data
+     *
+     * This is a core transformation function that converts raw Cursor conversation headers and
+     * bubble data into enriched, enhanced bubble objects ready for export. The function:
+     * 1. Iterates through conversation headers (which contain bubble IDs and message types)
+     * 2. Looks up corresponding raw bubbles by ID in the bubbleMap
+     * 3. Determines message type (user vs assistant) based on header type field
+     * 4. Creates enhanced bubbles by extracting and consolidating metadata from multiple sources:
+     *    - Tool results, console logs, code blocks from the bubble itself
+     *    - Context information from messageRequestContextMap
+     *    - Code diffs from codeBlockDiffMap
+     *    - File checkpoints from checkpointMap
+     * 5. Filters out empty bubbles (no text, tool results, or console logs) to keep only meaningful content
+     * 6. Tracks unique workspace hashes that bubbles belong to for workspace association
+     *
+     * This process enriches basic bubble data with all available context and metadata, creating
+     * a comprehensive representation of each conversation turn.
+     *
+     * @param conversationHeaders - Array of header objects containing bubble IDs and types (1=user, other=ai)
+     * @param bubbleMap - Map of bubble IDs to raw RawCursorBubbleRaw objects
+     * @param bubbleWorkspaceMap - Map of bubble IDs to their workspace hash identifiers
+     * @param messageRequestContextMap - Map of bubble IDs to RawCursorMessageRequestContext arrays
+     * @param codeBlockDiffMap - Map of bubble IDs to RawCursorCodeDiff arrays
+     * @param checkpointMap - Map of bubble IDs to RawCursorFileCheckpoint objects with checkpointId
+     * @returns Object containing enhanced bubbles array and set of workspace hashes used by these bubbles
+     */
+    private processBubbleHeaders;
+    /**
+     * Load and process all conversations from the database for a specific workspace
+     *
+     * Queries the database for all composer conversation data, filters to workspace-specific
+     * composers, parses each conversation's headers, creates enhanced bubbles, and returns
+     * conversation objects with metadata. Tracks and logs statistics on parsed vs skipped
+     * conversations (not in workspace, no headers, no extractable bubbles).
+     *
+     * @param db - Better-sqlite3 database instance
+     * @param workspacePath - Path to the workspace directory
+     * @param workspaceComposers - Set of composer IDs belonging to this workspace
+     * @param bubbleMap - Map of bubble IDs to raw RawCursorBubbleRaw objects
+     * @param bubbleWorkspaceMap - Map of bubble IDs to their workspace hashes
+     * @param messageRequestContextMap - Map of bubble IDs to RawCursorMessageRequestContext arrays
+     * @param codeBlockDiffMap - Map of bubble IDs to RawCursorCodeDiff arrays
+     * @param checkpointMap - Map of bubble IDs to RawCursorFileCheckpoint objects
+     * @returns Array of conversation objects with bubbles and metadata
+     */
+    private processConversations;
+    /**
+     * Safely parse JSON strings with graceful fallback to original value
+     *
+     * Attempts to parse a string as JSON. If parsing succeeds, returns the parsed object.
+     * If parsing fails or value is not a string, returns the original value unchanged.
+     * Used for fields that may contain either pre-parsed objects or JSON strings.
+     *
+     * @param value - Value to parse, may be string, object, or any other type
+     * @returns Parsed JSON object if string input, original value otherwise
+     */
+    private safeParseJSON;
+}