byterover-cli 0.2.1 → 0.3.0

package/dist/infra/parsers/clean/clean-parser-service-factory.js

@@ -0,0 +1,80 @@
+/**
+ * Clean Parser Service Factory
+ * Routes IDE-based clean parsing requests to the appropriate clean parser service
+ * Supports: Claude Code, Cursor, GitHub Copilot, Codex
+ */
+import { ClaudeCleanService } from './clean-claude-service.js';
+import { CodexCleanService } from './clean-codex-service.js';
+import { CopilotCleanService } from './clean-copilot-service.js';
+import { CursorCleanService } from './clean-cursor-service.js';
+/**
+ * Clean Parser Service Factory
+ * Creates and returns appropriate clean parser service for the given IDE
+ */
+export class CleanParserServiceFactory {
+    static SUPPORTED_IDES = ['Claude Code', 'Cursor', 'Github Copilot', 'Codex'];
+    /**
+     * Create a clean parser service for the specified IDE
+     *
+     * Factory method that instantiates the appropriate clean parser service
+     * based on the provided IDE type. Routes to specialized service classes.
+     *
+     * @param ide - The IDE type: 'Claude Code', 'Cursor', 'Github Copilot', or 'Codex'
+     * @returns The appropriate clean parser service instance
+     * @throws Error if IDE is not supported
+     */
+    static createCleanParserService(ide) {
+        switch (ide) {
+            case 'Claude Code': {
+                return new ClaudeCleanService(ide);
+            }
+            case 'Codex': {
+                return new CodexCleanService(ide);
+            }
+            case 'Cursor': {
+                return new CursorCleanService(ide);
+            }
+            case 'Github Copilot': {
+                return new CopilotCleanService(ide);
+            }
+            default: {
+                throw new Error(`Unsupported IDE: ${ide}. Supported IDEs are: claude, cursor, copilot, codex`);
+            }
+        }
+    }
+    /**
+     * Get list of supported IDEs
+     *
+     * Returns array of all IDE types that have corresponding clean parser services.
+     *
+     * @returns Array of supported IDE type strings
+     */
+    static getSupportedIDEs() {
+        return [...this.SUPPORTED_IDES];
+    }
+    /**
+     * Check if IDE is supported
+     *
+     * Validates whether the provided IDE string corresponds to a supported IDE.
+     *
+     * @param ide - IDE name to validate
+     * @returns True if IDE is in supported list, false otherwise
+     */
+    static isSupported(ide) {
+        return this.getSupportedIDEs().includes(ide);
+    }
+    /**
+     * Parse and clean conversations for the specified IDE
+     *
+     * Creates appropriate service and delegates to its parse method to transform
+     * raw session data into clean normalized format. Returns sessions in-memory.
+     *
+     * @param ide - The IDE type (Claude Code, Cursor, Github Copilot, Codex)
+     * @param rawDir - Path to directory containing raw session files
+     * @returns Promise resolving to array of clean normalized sessions
+     */
+    static async parseConversations(ide, rawDir) {
+        const service = this.createCleanParserService(ide);
+        return service.parse(rawDir);
+    }
+}

package/dist/infra/parsers/clean/shared.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared transformation utilities for all clean parsers
+ * Provides centralized session normalization implementation
+ */
+import { CleanMessage, CleanSession, ContentBlock, SessionType } from '../../../core/domain/entities/parser.js';
+import { ISessionNormalizer } from '../../../core/interfaces/parser/i-session-normalizer.js';
+/**
+ * Session Normalizer implementation
+ * Provides shared normalization utilities for all clean parsers
+ */
+export declare class SessionNormalizer implements ISessionNormalizer {
+    /**
+     * Add turn_id to each message based on timestamp order
+     *
+     * Assigns sequential turn_id values (1-based) to all messages to track
+     * their order in the conversation.
+     *
+     * @param messages - Array of messages to assign turn IDs to
+     * @returns Array of messages with turn_id property added
+     */
+    addTurnIds(messages: CleanMessage[]): CleanMessage[];
+    /**
+     * Combine tool_use and tool_result messages
+     *
+     * Merges separate tool_use and tool_result content blocks into single blocks
+     * with embedded output. Removes standalone tool_result blocks after combining.
+     * Two-pass algorithm: first collect results by ID, then merge with tool_use blocks.
+     *
+     * @param messages - Array of clean messages to process
+     * @returns Array of messages with combined tool execution blocks
+     */
+    combineToolResults(messages: CleanMessage[]): CleanMessage[];
+    /**
+     * Extract unique workspace paths from session messages and metadata
+     *
+     * Collects workspace paths from multiple sources: existing paths, message cwd properties,
+     * and metadata cwd property. Removes duplicates and sorts alphabetically.
+     *
+     * @param messages - Array of clean messages to extract paths from
+     * @param metadata - Session metadata object (may contain cwd property)
+     * @param existingPaths - Optional pre-existing paths to include
+     * @returns Sorted array of unique workspace paths
+     */
+    extractWorkspacePaths(messages: CleanMessage[], metadata: unknown, existingPaths?: string[]): string[];
+    /**
+     * Normalize message content to always be an array of content blocks
+     *
+     * Converts various content formats (string, array, object) into a standardized
+     * array of ContentBlock objects for consistent processing.
+     *
+     * @param content - Content to normalize (can be string, array of blocks, object, or any value)
+     * @returns Array of normalized ContentBlock objects
+     */
+    normalizeContent(content: unknown): ContentBlock[];
+    /**
+     * Normalize a single content block
+     *
+     * Converts a block into a properly typed ContentBlock. Infers the block type
+     * from its properties if not explicitly specified (text, thinking, tool_use, tool_result).
+     *
+     * @param block - Block to normalize (string, object, or any value)
+     * @returns Normalized ContentBlock with proper type inference
+     */
+    normalizeContentBlock(block: unknown): ContentBlock;
+    /**
+     * Normalize Claude session format
+     *
+     * Transforms raw session data into standardized CleanSession format. Normalizes message
+     * content to content blocks, combines tool calls with results, assigns turn IDs,
+     * and extracts workspace paths. Handles sessions from Claude, Copilot, Cursor, and Codex.
+     *
+     * @param session - Raw session object with messages and metadata
+     * @param sessionType - Type of session (Claude, Copilot, Cursor, Codex)
+     * @returns Normalized CleanSession with standardized format
+     */
+    normalizeSession(session: Record<string, unknown>, sessionType?: SessionType): CleanSession;
+}
+export declare const sessionNormalizer: SessionNormalizer;
+export declare function normalizeClaudeSession(session: Record<string, unknown>, sessionType?: SessionType): CleanSession;
+export declare function normalizeContent(content: unknown): ContentBlock[];
+export declare function normalizeContentBlock(block: unknown): ContentBlock;
+export declare function combineToolResults(messages: CleanMessage[]): CleanMessage[];
+export declare function addTurnIds(messages: CleanMessage[]): CleanMessage[];
+export declare function extractWorkspacePaths(messages: CleanMessage[], metadata: unknown, existingPaths?: string[]): string[];

package/dist/infra/parsers/clean/shared.js

@@ -0,0 +1,273 @@
+/**
+ * Shared transformation utilities for all clean parsers
+ * Provides centralized session normalization implementation
+ */
+/**
+ * Session Normalizer implementation
+ * Provides shared normalization utilities for all clean parsers
+ */
+export class SessionNormalizer {
+    /**
+     * Add turn_id to each message based on timestamp order
+     *
+     * Assigns sequential turn_id values (1-based) to all messages to track
+     * their order in the conversation.
+     *
+     * @param messages - Array of messages to assign turn IDs to
+     * @returns Array of messages with turn_id property added
+     */
+    addTurnIds(messages) {
+        return messages.map((msg, index) => ({
+            ...msg,
+            // eslint-disable-next-line camelcase
+            turn_id: index + 1,
+        }));
+    }
+    /**
+     * Combine tool_use and tool_result messages
+     *
+     * Merges separate tool_use and tool_result content blocks into single blocks
+     * with embedded output. Removes standalone tool_result blocks after combining.
+     * Two-pass algorithm: first collect results by ID, then merge with tool_use blocks.
+     *
+     * @param messages - Array of clean messages to process
+     * @returns Array of messages with combined tool execution blocks
+     */
+    combineToolResults(messages) {
+        const combined = [];
+        const toolResults = {};
+        // First pass: collect tool results by tool_use_id
+        for (const msg of messages) {
+            for (const block of msg.content) {
+                if (block.type === 'tool_result') {
+                    const toolBlock = block;
+                    toolResults[toolBlock.tool_use_id] = toolBlock;
+                }
+            }
+        }
+        // Second pass: combine tool_use with results
+        for (const msg of messages) {
+            const combinedContent = [];
+            for (const block of msg.content) {
+                if (block.type === 'tool_use') {
+                    const toolBlock = block;
+                    if (toolBlock.id && toolResults[toolBlock.id]) {
+                        // Attach result to tool_use, preserving tool_use_id
+                        const result = toolResults[toolBlock.id];
+                        const resultData = { ...result };
+                        delete resultData.tool_use_id;
+                        combinedContent.push({
+                            ...toolBlock,
+                            output: resultData,
+                            // eslint-disable-next-line camelcase
+                            tool_use_id: toolBlock.id,
+                        });
+                    }
+                    else {
+                        combinedContent.push(block);
+                    }
+                }
+                else if (block.type !== 'tool_result') {
+                    // Skip tool_result blocks (they're now merged)
+                    combinedContent.push(block);
+                }
+            }
+            if (combinedContent.length > 0) {
+                combined.push({
+                    ...msg,
+                    content: combinedContent,
+                });
+            }
+        }
+        return combined;
+    }
+    /**
+     * Extract unique workspace paths from session messages and metadata
+     *
+     * Collects workspace paths from multiple sources: existing paths, message cwd properties,
+     * and metadata cwd property. Removes duplicates and sorts alphabetically.
+     *
+     * @param messages - Array of clean messages to extract paths from
+     * @param metadata - Session metadata object (may contain cwd property)
+     * @param existingPaths - Optional pre-existing paths to include
+     * @returns Sorted array of unique workspace paths
+     */
+    extractWorkspacePaths(messages, metadata, existingPaths) {
+        const paths = new Set();
+        // Start with existing paths if provided
+        if (existingPaths && Array.isArray(existingPaths)) {
+            for (const p of existingPaths) {
+                if (p && typeof p === 'string') {
+                    paths.add(p);
+                }
+            }
+        }
+        // Extract from messages
+        for (const msg of messages) {
+            const { cwd } = msg;
+            if (cwd && typeof cwd === 'string') {
+                paths.add(cwd);
+            }
+        }
+        // Extract from metadata
+        if (typeof metadata === 'object' && metadata !== null) {
+            const metaObj = metadata;
+            if (metaObj.cwd && typeof metaObj.cwd === 'string') {
+                paths.add(metaObj.cwd);
+            }
+        }
+        return [...paths].sort();
+    }
+    /**
+     * Normalize message content to always be an array of content blocks
+     *
+     * Converts various content formats (string, array, object) into a standardized
+     * array of ContentBlock objects for consistent processing.
+     *
+     * @param content - Content to normalize (can be string, array of blocks, object, or any value)
+     * @returns Array of normalized ContentBlock objects
+     */
+    normalizeContent(content) {
+        if (Array.isArray(content)) {
+            return content.map((block) => this.normalizeContentBlock(block));
+        }
+        if (typeof content === 'string') {
+            return [
+                {
+                    text: content,
+                    type: 'text',
+                },
+            ];
+        }
+        if (typeof content === 'object' && content !== null) {
+            return [this.normalizeContentBlock(content)];
+        }
+        return [];
+    }
+    /**
+     * Normalize a single content block
+     *
+     * Converts a block into a properly typed ContentBlock. Infers the block type
+     * from its properties if not explicitly specified (text, thinking, tool_use, tool_result).
+     *
+     * @param block - Block to normalize (string, object, or any value)
+     * @returns Normalized ContentBlock with proper type inference
+     */
+    normalizeContentBlock(block) {
+        if (typeof block === 'string') {
+            return {
+                text: block,
+                type: 'text',
+            };
+        }
+        if (typeof block !== 'object' || block === null) {
+            return { text: String(block), type: 'text' };
+        }
+        const blockObj = block;
+        const normalized = { ...blockObj };
+        // Remove redundant 'signature' property
+        delete normalized.signature;
+        // Ensure proper type for content blocks
+        if (!normalized.type) {
+            if ('text' in normalized) {
+                normalized.type = 'text';
+            }
+            else if ('thinking' in normalized) {
+                normalized.type = 'thinking';
+            }
+            else if ('name' in normalized && 'input' in normalized) {
+                normalized.type = 'tool_use';
+            }
+            else if ('tool_use_id' in normalized) {
+                normalized.type = 'tool_result';
+            }
+            else {
+                normalized.type = 'text';
+            }
+        }
+        return normalized;
+    }
+    /**
+     * Normalize Claude session format
+     *
+     * Transforms raw session data into standardized CleanSession format. Normalizes message
+     * content to content blocks, combines tool calls with results, assigns turn IDs,
+     * and extracts workspace paths. Handles sessions from Claude, Copilot, Cursor, and Codex.
+     *
+     * @param session - Raw session object with messages and metadata
+     * @param sessionType - Type of session (Claude, Copilot, Cursor, Codex)
+     * @returns Normalized CleanSession with standardized format
+     */
+    normalizeSession(session, sessionType = 'Claude') {
+        // Normalize messages
+        const rawMessages = session.messages || [];
+        let normalizedMessages = rawMessages.map((rawMsg) => {
+            const msg = rawMsg;
+            const msgType = msg.type || 'user';
+            const timestamp = msg.timestamp || new Date().toISOString();
+            // Normalize content to array format
+            const contentArray = this.normalizeContent(msg.content);
+            // Set default type for content blocks based on message type
+            const processedContent = contentArray.map((block) => {
+                if (msgType === 'user' && !block.type) {
+                    return { ...block, type: 'text' };
+                }
+                if (msgType === 'assistant' && !block.type) {
+                    return { ...block, type: 'thinking' };
+                }
+                return block;
+            });
+            const normalizedMsg = {
+                content: processedContent,
+                timestamp,
+                type: msgType,
+            };
+            // Copy over other properties except content, type, and timestamp
+            for (const [key, value] of Object.entries(msg)) {
+                if (key !== 'content' && key !== 'type' && key !== 'timestamp' && value !== undefined) {
+                    ;
+                    normalizedMsg[key] = value;
+                }
+            }
+            return normalizedMsg;
+        });
+        // Combine tool_use and tool_result messages
+        normalizedMessages = this.combineToolResults(normalizedMessages);
+        // Add turn_id based on timestamp order
+        normalizedMessages = this.addTurnIds(normalizedMessages);
+        // Extract unique workspace paths - preserve existing ones if already set
+        const existingPaths = session.workspacePaths || undefined;
+        const workspacePaths = this.extractWorkspacePaths(normalizedMessages, session.metadata, existingPaths);
+        // Return normalized session
+        return {
+            id: session.id || '',
+            messages: normalizedMessages,
+            metadata: session.metadata,
+            timestamp: session.timestamp || Date.now(),
+            title: session.title || '',
+            type: sessionType,
+            workspacePaths: workspacePaths.length > 0 ? workspacePaths : [],
+        };
+    }
+}
+// Export singleton instance for convenience
+export const sessionNormalizer = new SessionNormalizer();
+// Re-export standalone functions for backward compatibility
+export function normalizeClaudeSession(session, sessionType = 'Claude') {
+    return sessionNormalizer.normalizeSession(session, sessionType);
+}
+export function normalizeContent(content) {
+    return sessionNormalizer.normalizeContent(content);
+}
+export function normalizeContentBlock(block) {
+    return sessionNormalizer.normalizeContentBlock(block);
+}
+export function combineToolResults(messages) {
+    return sessionNormalizer.combineToolResults(messages);
+}
+export function addTurnIds(messages) {
+    return sessionNormalizer.addTurnIds(messages);
+}
+export function extractWorkspacePaths(messages, metadata, existingPaths) {
+    return sessionNormalizer.extractWorkspacePaths(messages, metadata, existingPaths);
+}

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

@@ -0,0 +1,195 @@
+/**
+ * Claude Code Raw Service
+ * Consolidates ClaudeCodeParser + ClaudeRawParser
+ * Parses JSONL transcript files from ~/.claude/projects/
+ */
+import { Agent } from '../../../core/domain/entities/agent.js';
+import { IRawParserService } from '../../../core/interfaces/parser/i-raw-parser-service.js';
+/**
+ * Claude Raw Service - Wraps parser and handles file I/O and output management
+ */
+export declare class ClaudeRawService implements IRawParserService {
+    private ide;
+    /**
+     * Initialize Claude Raw Service
+     *
+     * @param ide - The IDE type (Claude Code)
+     */
+    constructor(ide: Agent);
+    /**
+     * Main entry point - Parse Claude Code sessions from a custom directory
+     *
+     * Parses all JSONL transcript files from a custom Claude projects directory,
+     * extracts session information, and writes normalized JSON files to output directory.
+     * Organizes output by Claude project folder name. Returns success status.
+     *
+     * @param customDir - Path to directory containing Claude Code session files
+     * @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>;
+    /**
+     * Calculate aggregate session metadata from transcript entries
+     *
+     * Aggregates token usage (input, output, cache), counts message types, extracts workspace,
+     * workspace path, and timestamps. Returns comprehensive metadata about the session including
+     * duration, token costs, and message counts for analysis and reporting.
+     *
+     * @param entries - Array of transcript entries from JSONL file
+     * @param messages - Parsed messages array (for count verification)
+     * @param logPath - Log file path (used to extract workspace information)
+     * @returns RawClaudeSessionMetadata object with aggregated statistics
+     */
+    private calculateMetadata;
+    /**
+     * Convert Claude Code transcript entries to normalized messages
+     *
+     * Transforms raw JSONL transcript entries (user, assistant, system) into standardized
+     * RawClaudeRawMessage objects with preserved content, timestamps, and token counts.
+     * Filters out invalid entries without content.
+     *
+     * @param entries - Array of RawClaudeTranscriptEntry objects from JSONL file
+     * @returns Array of normalized RawClaudeRawMessage objects
+     */
+    private convertToMessages;
+    /**
+     * Create normalized message from transcript entry
+     *
+     * Converts a single transcript entry (user or assistant) into a normalized message.
+     * Extracts content blocks, preserving array structure for multi-block content but
+     * converting single text blocks to plain strings for backward compatibility.
+     * Includes token counts if available and preserves cwd if present.
+     *
+     * @param entry - Transcript entry with message content
+     * @param type - Message type: 'user' or 'assistant'
+     * @returns Normalized RawClaudeRawMessage object
+     * @throws Error if message field is missing
+     */
+    private createMessageFromEntry;
+    /**
+     * Create or get subdirectory within output directory
+     *
+     * Creates a subdirectory within the output directory if it doesn't exist.
+     * Uses recursive mode to create parent directories as needed.
+     *
+     * @param outputDir - Base output directory path
+     * @param subdirName - Name of subdirectory to create
+     * @returns Full path to the created or existing subdirectory
+     */
+    private createSubdirectory;
+    /**
+     * Create system message from transcript entry
+     *
+     * Converts a system-type transcript entry into a normalized message object.
+     * System messages typically contain metadata or initial instructions.
+     * Preserves cwd if present in the entry.
+     *
+     * @param entry - Transcript entry with type='system'
+     * @returns Normalized RawClaudeRawMessage with type='system'
+     */
+    private createSystemMessage;
+    /**
+     * Extract and normalize content blocks from message
+     *
+     * Handles multiple content formats: null/undefined (empty array), strings (wrapped as text block),
+     * arrays of blocks/strings (normalized to ContentBlock array), objects with type (treated as block),
+     * and other objects (stringified as text). Produces consistent ContentBlock array output.
+     *
+     * @param content - Raw message content in various formats
+     * @returns Array of normalized ContentBlock objects
+     */
+    private extractContentBlocks;
+    /**
+     * Extract session ID from Claude Code log file path
+     *
+     * Parses the filename from the log path to extract the session ID.
+     * Claude Code session IDs are typically UUIDs in the JSONL filename.
+     * Removes the .jsonl extension to get the session ID.
+     *
+     * @param logPath - Path to Claude Code session log file
+     * @returns Session ID extracted from the filename
+     */
+    private extractSessionId;
+    /**
+     * Extract and sort session start and end timestamps
+     *
+     * Collects timestamps from transcript entries, filters out empty values,
+     * sorts them chronologically, and returns first (startedAt) and last (endedAt).
+     * Returns default current timestamp if no valid timestamps found.
+     *
+     * @param entries - Array of transcript entries with optional timestamp fields
+     * @returns RawClaudeTimestamps object with startedAt and optional endedAt ISO timestamp strings
+     */
+    private extractTimestamps;
+    /**
+     * Extract session title from first user message
+     *
+     * Uses the first line of the first user message as the session title.
+     * Truncates to TITLE_MAX_LENGTH (100 chars) and appends "..." if truncated.
+     * Returns default title if no user messages found or first message is not text.
+     *
+     * @param messages - Array of parsed session messages
+     * @returns Session title string (max 100 characters)
+     */
+    private extractTitle;
+    /**
+     * Extract workspace information from Claude Code log file path
+     *
+     * Parses the log path to extract workspace information. Claude Code stores projects
+     * in ~/.claude/projects/-path-to-workspace format where slashes are replaced with dashes.
+     * Extracts and reconstructs the original workspace path and repository name.
+     * Returns default path object if extraction fails.
+     *
+     * @param logPath - Claude Code session log file path
+     * @returns RawClaudeWorkspaceMetadata with workspace path and optional repository name/url
+     */
+    private extractWorkspace;
+    /**
+     * Get the output directory path for raw parser results
+     *
+     * Returns the standardized output directory path for storing raw parsed sessions.
+     * Directory is relative to current working directory under .brv/logs/{ide}/raw
+     *
+     * @param ide - IDE agent type (used as directory component)
+     * @param override - Optional custom output directory (overrides default)
+     * @returns Full path to raw output directory
+     */
+    private getOutputDir;
+    /**
+     * Parse all Claude Code session logs in a directory
+     *
+     * Finds all JSONL files in the directory (excluding combined files), parses them in parallel,
+     * and returns array of successfully parsed sessions sorted by start time.
+     * Collects and reports any parse errors without failing completely.
+     *
+     * @param dirPath - Path to directory containing JSONL session files
+     * @returns Promise resolving to array of parsed RawClaudeRawSession objects
+     * @throws Error if directory cannot be read
+     */
+    private parseSessionDirectory;
+    /**
+     * Parse a single Claude Code session log file
+     *
+     * Validates log file format, reads JSONL content, parses each line as a transcript entry,
+     * converts entries to messages, calculates session metadata, and extracts session title.
+     * Throws detailed error if log file is invalid or unparseable.
+     *
+     * @param logPath - Absolute path to Claude Code session JSONL file
+     * @returns Promise resolving to parsed RawClaudeRawSession object
+     * @throws Error if file is invalid or cannot be parsed
+     */
+    private parseSessionLog;
+    /**
+     * Validate Claude Code log file format and existence
+     *
+     * Checks three validation criteria:
+     * 1. Path contains /.claude/projects/ directory marker
+     * 2. File has .jsonl extension
+     * 3. File exists on filesystem
+     * Returns false silently if any check fails.
+     *
+     * @param logPath - Path to file to validate
+     * @returns Promise resolving to true if file is valid Claude Code log file, false otherwise
+     */
+    private validateLogFile;
+}