byterover-cli 1.5.0 → 1.7.0

package/dist/agent/infra/environment/environment-context-builder.js

@@ -0,0 +1,256 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SystemPromptError } from '../../core/domain/errors/system-prompt-error.js';
+import { EnvironmentContextOptionsSchema, } from '../system-prompt/schemas.js';
+/**
+ * Patterns to exclude from file tree.
+ */
+const EXCLUDE_PATTERNS = [
+    'node_modules',
+    '.git',
+    '.brv',
+    'dist',
+    'build',
+    '.next',
+    'coverage',
+    '.DS_Store',
+    '.env',
+    '.env.local',
+    '__pycache__',
+    '.pytest_cache',
+    '.venv',
+    'venv',
+    '.idea',
+    '.vscode',
+    '*.log',
+    '.turbo',
+    '.cache',
+];
+/**
+ * Builds environment context for system prompts and sandbox execution.
+ *
+ * Gathers information about:
+ * - Working directory
+ * - Git repository status
+ * - Platform and OS version
+ * - Project file tree
+ * - .brv directory structure
+ */
+export class EnvironmentContextBuilder {
+    /**
+     * Build the complete environment context.
+     *
+     * @param options - Configuration options (validated against EnvironmentContextOptionsSchema)
+     * @returns Environment context object
+     */
+    async build(options) {
+        // Validate options with Zod schema
+        const parseResult = EnvironmentContextOptionsSchema.safeParse(options);
+        if (!parseResult.success) {
+            const errorMessages = parseResult.error.errors
+                .map((err) => `${err.path.join('.')}: ${err.message}`)
+                .join('; ');
+            throw SystemPromptError.configInvalid(errorMessages, parseResult.error.errors);
+        }
+        const validatedOptions = parseResult.data;
+        const { includeBrvStructure = true, includeFileTree = true, maxFileTreeDepth = 3, maxFileTreeEntries = 100, workingDirectory, } = validatedOptions;
+        const isGitRepository = this.detectGitRepository(workingDirectory);
+        let fileTree = '';
+        if (includeFileTree) {
+            fileTree = this.buildFileTree(workingDirectory, maxFileTreeDepth, maxFileTreeEntries);
+        }
+        let brvStructure = '';
+        if (includeBrvStructure) {
+            brvStructure = this.buildBrvStructure(workingDirectory);
+        }
+        return {
+            brvStructure,
+            fileTree,
+            isGitRepository,
+            nodeVersion: process.version,
+            osVersion: os.release(),
+            platform: os.platform(),
+            workingDirectory,
+        };
+    }
+    /**
+     * Build an explanation of the .brv directory structure.
+     *
+     * @param dir - Working directory path
+     * @returns Formatted .brv structure explanation
+     */
+    buildBrvStructure(dir) {
+        const brvDir = path.join(dir, '.brv');
+        if (!fs.existsSync(brvDir)) {
+            return '<brv-structure>\nByteRover not initialized (.brv directory not found)\n</brv-structure>';
+        }
+        // Build actual structure by reading the directory
+        const structure = ['<brv-structure>', '.brv/'];
+        try {
+            const entries = fs.readdirSync(brvDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const description = this.getBrvDirectoryDescription(entry.name);
+                    structure.push(`  ${entry.name}/          ${description}`);
+                }
+                else {
+                    const description = this.getBrvFileDescription(entry.name);
+                    structure.push(`  ${entry.name}          ${description}`);
+                }
+            }
+        }
+        catch {
+            structure.push('  (unable to read directory contents)');
+        }
+        structure.push('</brv-structure>');
+        return structure.join('\n');
+    }
+    /**
+     * Build a formatted file tree of the project.
+     *
+     * @param dir - Root directory to start from
+     * @param maxDepth - Maximum traversal depth
+     * @param maxEntries - Maximum number of entries to include
+     * @returns Formatted file tree string
+     */
+    buildFileTree(dir, maxDepth, maxEntries) {
+        const entriesCount = { value: 0 };
+        const truncatedCount = { value: 0 };
+        const lines = ['<files>'];
+        this.traverseDirectory({
+            currentDepth: 0,
+            dir,
+            entriesCount,
+            lines,
+            maxDepth,
+            maxEntries,
+            truncatedCount,
+        });
+        if (truncatedCount.value > 0) {
+            lines.push(`[${truncatedCount.value} entries truncated]`);
+        }
+        lines.push('</files>');
+        return lines.join('\n');
+    }
+    /**
+     * Check if a directory is a git repository.
+     *
+     * @param dir - Directory path to check
+     * @returns True if the directory contains a .git folder
+     */
+    detectGitRepository(dir) {
+        try {
+            const gitDir = path.join(dir, '.git');
+            return fs.existsSync(gitDir);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get description for a .brv directory.
+     *
+     * @param name - Directory name
+     * @returns Description string
+     */
+    getBrvDirectoryDescription(name) {
+        const descriptions = {
+            blobs: '# Storage for conversation history',
+            'context-tree': '# Semantic knowledge organized by domain',
+            logs: '# Debug logs for troubleshooting',
+        };
+        return descriptions[name] ?? '';
+    }
+    /**
+     * Get description for a .brv file.
+     *
+     * @param name - File name
+     * @returns Description string
+     */
+    getBrvFileDescription(name) {
+        const descriptions = {
+            'config.json': '# Project configuration',
+        };
+        return descriptions[name] ?? '';
+    }
+    /**
+     * Check if a file or directory should be excluded from the tree.
+     *
+     * @param name - File or directory name
+     * @returns True if should be excluded
+     */
+    shouldExclude(name) {
+        for (const pattern of EXCLUDE_PATTERNS) {
+            if (pattern.startsWith('*')) {
+                // Wildcard pattern (e.g., *.log)
+                const extension = pattern.slice(1);
+                if (name.endsWith(extension)) {
+                    return true;
+                }
+            }
+            else if (name === pattern) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Recursively traverse a directory and build tree lines.
+     *
+     * @param options - Traversal options
+     * @param options.dir - Current directory path
+     * @param options.maxDepth - Maximum depth to traverse
+     * @param options.maxEntries - Maximum entries to include
+     * @param options.currentDepth - Current traversal depth
+     * @param options.entriesCount - Counter for entries added (mutable object with value property)
+     * @param options.truncatedCount - Counter for truncated entries (mutable object with value property)
+     * @param options.lines - Array to append lines to
+     */
+    traverseDirectory(options) {
+        const { currentDepth, dir, entriesCount, lines, maxDepth, maxEntries, truncatedCount } = options;
+        if (currentDepth >= maxDepth) {
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // Filter and sort: directories first, then alphabetically
+        const filteredEntries = entries
+            .filter((entry) => !this.shouldExclude(entry.name))
+            .sort((a, b) => {
+            if (a.isDirectory() && !b.isDirectory())
+                return -1;
+            if (!a.isDirectory() && b.isDirectory())
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        const indent = '  '.repeat(currentDepth);
+        for (const entry of filteredEntries) {
+            if (entriesCount.value >= maxEntries) {
+                truncatedCount.value += filteredEntries.length - filteredEntries.indexOf(entry);
+                break;
+            }
+            entriesCount.value++;
+            if (entry.isDirectory()) {
+                lines.push(`${indent}${entry.name}/`);
+                this.traverseDirectory({
+                    currentDepth: currentDepth + 1,
+                    dir: path.join(dir, entry.name),
+                    entriesCount,
+                    lines,
+                    maxDepth,
+                    maxEntries,
+                    truncatedCount,
+                });
+            }
+            else {
+                lines.push(`${indent}${entry.name}`);
+            }
+        }
+    }
+}

package/dist/agent/infra/events/event-emitter.d.ts

@@ -0,0 +1,137 @@
+import { EventEmitter } from 'node:events';
+import type { AgentEventMap, SessionEventMap } from '../../core/domain/agent-events/types.js';
+import type { EventListenerOptions, IEventEmitter } from '../../core/interfaces/i-event-emitter.js';
+/**
+ * Base implementation of a type-safe event emitter.
+ *
+ * Extends Node.js EventEmitter with TypeScript type safety and AbortController support.
+ * This follows the pattern from Dexto's event system.
+ *
+ * Features:
+ * - Type-safe emit/on/once/off methods
+ * - AbortController integration for automatic listener cleanup
+ * - Proper handling of void payloads
+ * - WeakMap-based tracking for signal-listener associations
+ *
+ * @template TEventMap - Map of event names to their payload types
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   'data:received': { value: number };
+ *   'data:cleared': void;
+ * }
+ *
+ * class MyEventBus extends BaseTypedEventEmitter<MyEvents> {}
+ *
+ * const bus = new MyEventBus();
+ * bus.emit('data:received', { value: 42 });
+ * bus.emit('data:cleared');
+ *
+ * // With AbortController
+ * const controller = new AbortController();
+ * bus.on('data:received', (data) => console.log(data.value), { signal: controller.signal });
+ * controller.abort(); // Automatically removes listener
+ * ```
+ */
+export declare class BaseTypedEventEmitter<TEventMap extends object> extends EventEmitter implements IEventEmitter<TEventMap> {
+    /**
+     * WeakMap tracking AbortSignal → Set<listener function>.
+     * Used to automatically remove listeners when signals are aborted.
+     */
+    private readonly signalListeners;
+    /**
+     * Emit an event with optional payload.
+     *
+     * @param eventName - Name of the event to emit
+     * @param payload - Event payload (omit for void events)
+     * @returns true if the event had listeners, false otherwise
+     */
+    emit<K extends keyof TEventMap>(eventName: K, ...payload: TEventMap[K] extends void ? [] : [TEventMap[K]]): boolean;
+    emit(eventName: string, ...args: never[]): boolean;
+    /**
+     * Remove an event listener.
+     *
+     * @param eventName - Name of the event
+     * @param listener - Callback function to remove
+     * @returns this (for chaining)
+     */
+    off<K extends keyof TEventMap>(eventName: K, listener: TEventMap[K] extends void ? () => void : (payload: TEventMap[K]) => void): this;
+    off(eventName: string | symbol, listener: (data?: unknown) => void): this;
+    /**
+     * Register an event listener.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param listener - Callback function
+     * @param options - Optional AbortSignal for automatic cleanup
+     * @returns this (for chaining)
+     */
+    on<K extends keyof TEventMap>(eventName: K, listener: TEventMap[K] extends void ? () => void : (payload: TEventMap[K]) => void, options?: EventListenerOptions): this;
+    on(eventName: string | symbol, listener: (data?: unknown) => void): this;
+    /**
+     * Register a one-time event listener.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param listener - Callback function
+     * @param options - Optional AbortSignal for automatic cleanup
+     * @returns this (for chaining)
+     */
+    once<K extends keyof TEventMap>(eventName: K, listener: TEventMap[K] extends void ? () => void : (payload: TEventMap[K]) => void, options?: EventListenerOptions): this;
+    once(eventName: string | symbol, listener: (data?: unknown) => void): this;
+    /**
+     * Setup automatic cleanup when AbortSignal fires.
+     *
+     * @param eventName - Event name
+     * @param listener - Listener function to remove
+     * @param signal - AbortSignal to watch
+     */
+    private setupAbortCleanup;
+}
+/**
+ * Event bus for agent-level events.
+ *
+ * Handles global agent events like state changes, conversation resets, etc.
+ * All events include sessionId to track which session triggered the event.
+ *
+ * @example
+ * ```typescript
+ * const agentBus = new AgentEventBus();
+ *
+ * agentBus.on('cipher:stateChanged', (payload) => {
+ *   console.log(`State changed: ${payload.field} in session ${payload.sessionId}`);
+ * });
+ *
+ * agentBus.emit('cipher:stateChanged', {
+ *   field: 'model',
+ *   newValue: 'gemini-2.5-flash',
+ *   sessionId: 'session-123'
+ * });
+ * ```
+ */
+export declare class AgentEventBus extends BaseTypedEventEmitter<AgentEventMap> {
+}
+/**
+ * Event bus for session-level events.
+ *
+ * Handles session-scoped events like LLM thinking, tool calls, responses, etc.
+ * Events do not include sessionId as they are already scoped to a specific session.
+ *
+ * Typically, these events are forwarded to the AgentEventBus with sessionId added.
+ *
+ * @example
+ * ```typescript
+ * const sessionBus = new SessionEventBus();
+ *
+ * sessionBus.on('llmservice:toolCall', (payload) => {
+ *   console.log(`Tool call: ${payload.toolName}`);
+ * });
+ *
+ * sessionBus.emit('llmservice:toolCall', {
+ *   toolName: 'read_file',
+ *   args: { filePath: '/path/to/file' },
+ *   callId: 'call-456'
+ * });
+ * ```
+ */
+export declare class SessionEventBus extends BaseTypedEventEmitter<SessionEventMap> {
+}

package/dist/agent/infra/file-system/binary-utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Checks if a file is binary based on extension and content analysis.
+ *
+ * Detection strategy:
+ * 1. Fast path: Check against known binary extensions
+ * 2. Check for null bytes (definitive binary indicator)
+ * 3. UTF-8 aware: Check for invalid UTF-8 sequences (replacement character)
+ * 4. Heuristic: Check for excessive control characters
+ *
+ * @param filePath - Path to the file (used for extension check)
+ * @param buffer - Buffer containing first N bytes of the file
+ * @returns true if the file is binary, false otherwise
+ */
+export declare function isBinaryFile(filePath: string, buffer: Buffer): boolean;
+/**
+ * Checks if a file is an image based on its extension.
+ * SVG files are excluded as they are text-based.
+ *
+ * @param filePath - Path to the file
+ * @returns true if the file is an image (excluding SVG)
+ */
+export declare function isImageFile(filePath: string): boolean;
+/**
+ * Checks if a file is a PDF. When buffer is provided, validates magic bytes (%PDF-).
+ * Searches within first 1KB to handle PDFs with leading whitespace/comments.
+ */
+export declare function isPdfFile(filePath: string, buffer?: Buffer): boolean;
+/**
+ * Gets the MIME type for an image or PDF file.
+ *
+ * @param filePath - Path to the file
+ * @returns MIME type string, or null if not a recognized image/PDF
+ */
+export declare function getMimeType(filePath: string): null | string;
+/**
+ * Checks if a file is a media file (only images supported at this point). PDFs are handled separately.
+ * @param filePath - Path to the file
+ */
+export declare function isMediaFile(filePath: string): boolean;
+/**
+ * Checks if a file is an Office document based on its extension.
+ * These files can be parsed for text extraction using officeparser.
+ *
+ * @param filePath - Path to the file
+ * @returns true if the file is an Office document
+ */
+export declare function isOfficeFile(filePath: string): boolean;
+/**
+ * Determines if a file should be returned as a base64 attachment.
+ *
+ * - Images: Always returned as attachment
+ * - PDFs: Depends on pdfMode ('base64' = attachment, 'text' = extract text)
+ * - Other files: Never returned as attachment
+ *
+ * @param filePath - Path to the file
+ * @param pdfMode - PDF read mode ('text' | 'base64'), defaults to 'text'
+ * @returns true if file should be returned as base64 attachment
+ */
+export declare function shouldReturnAsAttachment(filePath: string, pdfMode?: 'base64' | 'text'): boolean;

package/dist/agent/infra/file-system/binary-utils.js

@@ -0,0 +1,225 @@
+import path from 'node:path';
+/**
+ * Known binary file extensions for fast-path detection.
+ * These files are always treated as binary without content inspection.
+ * Sorted alphabetically as required by linter.
+ */
+const BINARY_EXTENSIONS = new Set([
+    '.7z',
+    '.a',
+    '.bin',
+    '.bz2',
+    '.class',
+    '.com',
+    '.dat',
+    '.db',
+    '.dll',
+    '.doc',
+    '.docx',
+    '.dylib',
+    '.exe',
+    '.gz',
+    '.jar',
+    '.lib',
+    '.o',
+    '.obj',
+    '.odp',
+    '.ods',
+    '.odt',
+    '.ppt',
+    '.pptx',
+    '.pyc',
+    '.pyo',
+    '.rar',
+    '.so',
+    '.sqlite',
+    '.sqlite3',
+    '.tar',
+    '.war',
+    '.wasm',
+    '.xls',
+    '.xlsx',
+    '.xz',
+    '.zip',
+]);
+/**
+ * Image file extensions that should be handled specially (base64 encoding).
+ * Sorted alphabetically as required by linter.
+ */
+const IMAGE_EXTENSIONS = new Set(['.bmp', '.gif', '.ico', '.jpeg', '.jpg', '.png', '.tif', '.tiff', '.webp']);
+/**
+ * Office document extensions that can be parsed for text extraction.
+ * Sorted alphabetically as required by linter.
+ */
+const OFFICE_EXTENSIONS = new Set([
+    '.docx',
+    '.odp',
+    '.ods',
+    '.odt',
+    '.pptx',
+    '.xlsx',
+]);
+/**
+ * PDF extension for special handling.
+ */
+const PDF_EXTENSION = '.pdf';
+/**
+ * PDF magic bytes: %PDF- (0x25 0x50 0x44 0x46 0x2D)
+ */
+const PDF_MAGIC_BYTES = Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2d]);
+/**
+ * Maximum offset to search for PDF magic bytes.
+ * PDFs may have whitespace or comments before the header.
+ */
+const PDF_MAGIC_SEARCH_LIMIT = 1024;
+/**
+ * SVG extension - treat as text, not image.
+ */
+const SVG_EXTENSION = '.svg';
+/**
+ * MIME type mappings for image and PDF files.
+ */
+const MIME_TYPES = {
+    '.bmp': 'image/bmp',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.tif': 'image/tiff',
+    '.tiff': 'image/tiff',
+    '.webp': 'image/webp',
+};
+/**
+ * Threshold for control character ratio to consider a file binary.
+ */
+const CONTROL_CHAR_THRESHOLD = 0.1;
+/**
+ * Unicode replacement character - indicates invalid UTF-8 sequence.
+ */
+const REPLACEMENT_CHAR = '\uFFFD';
+/**
+ * Checks if a file is binary based on extension and content analysis.
+ *
+ * Detection strategy:
+ * 1. Fast path: Check against known binary extensions
+ * 2. Check for null bytes (definitive binary indicator)
+ * 3. UTF-8 aware: Check for invalid UTF-8 sequences (replacement character)
+ * 4. Heuristic: Check for excessive control characters
+ *
+ * @param filePath - Path to the file (used for extension check)
+ * @param buffer - Buffer containing first N bytes of the file
+ * @returns true if the file is binary, false otherwise
+ */
+export function isBinaryFile(filePath, buffer) {
+    const ext = path.extname(filePath).toLowerCase();
+    // Fast path: known binary extensions
+    if (BINARY_EXTENSIONS.has(ext)) {
+        return true;
+    }
+    // Images and PDFs are binary but handled specially
+    if (isImageFile(filePath) || isPdfFile(filePath)) {
+        return true;
+    }
+    // Empty files are not binary
+    if (buffer.length === 0) {
+        return false;
+    }
+    // Null byte is a definitive binary indicator
+    if (buffer.includes(0)) {
+        return true;
+    }
+    // UTF-8 aware detection: invalid UTF-8 sequences produce replacement character
+    const str = buffer.toString('utf8');
+    if (str.includes(REPLACEMENT_CHAR)) {
+        return true;
+    }
+    // Count control characters (0x01-0x08, 0x0E-0x1F) - null bytes already handled above
+    let controlCharCount = 0;
+    for (const byte of buffer) {
+        if ((byte > 0 && byte < 9) || (byte > 13 && byte < 32)) {
+            controlCharCount++;
+        }
+    }
+    return controlCharCount / buffer.length > CONTROL_CHAR_THRESHOLD;
+}
+/**
+ * Checks if a file is an image based on its extension.
+ * SVG files are excluded as they are text-based.
+ *
+ * @param filePath - Path to the file
+ * @returns true if the file is an image (excluding SVG)
+ */
+export function isImageFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    // SVG is text-based, not a binary image
+    if (ext === SVG_EXTENSION) {
+        return false;
+    }
+    return IMAGE_EXTENSIONS.has(ext);
+}
+/**
+ * Checks if a file is a PDF. When buffer is provided, validates magic bytes (%PDF-).
+ * Searches within first 1KB to handle PDFs with leading whitespace/comments.
+ */
+export function isPdfFile(filePath, buffer) {
+    if (!buffer) {
+        return path.extname(filePath).toLowerCase() === PDF_EXTENSION;
+    }
+    if (path.extname(filePath).toLowerCase() !== PDF_EXTENSION) {
+        return false;
+    }
+    const searchLimit = Math.min(buffer.length, PDF_MAGIC_SEARCH_LIMIT);
+    return buffer.subarray(0, searchLimit).includes(PDF_MAGIC_BYTES);
+}
+/**
+ * Gets the MIME type for an image or PDF file.
+ *
+ * @param filePath - Path to the file
+ * @returns MIME type string, or null if not a recognized image/PDF
+ */
+export function getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return MIME_TYPES[ext] ?? null;
+}
+/**
+ * Checks if a file is a media file (only images supported at this point). PDFs are handled separately.
+ * @param filePath - Path to the file
+ */
+export function isMediaFile(filePath) {
+    return isImageFile(filePath);
+}
+/**
+ * Checks if a file is an Office document based on its extension.
+ * These files can be parsed for text extraction using officeparser.
+ *
+ * @param filePath - Path to the file
+ * @returns true if the file is an Office document
+ */
+export function isOfficeFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return OFFICE_EXTENSIONS.has(ext);
+}
+/**
+ * Determines if a file should be returned as a base64 attachment.
+ *
+ * - Images: Always returned as attachment
+ * - PDFs: Depends on pdfMode ('base64' = attachment, 'text' = extract text)
+ * - Other files: Never returned as attachment
+ *
+ * @param filePath - Path to the file
+ * @param pdfMode - PDF read mode ('text' | 'base64'), defaults to 'text'
+ * @returns true if file should be returned as base64 attachment
+ */
+export function shouldReturnAsAttachment(filePath, pdfMode) {
+    // Images are always returned as attachments
+    if (isImageFile(filePath)) {
+        return true;
+    }
+    // PDFs depend on pdfMode (if pdfMode is 'base64', return true)
+    if (isPdfFile(filePath) && pdfMode === 'base64') {
+        return true;
+    }
+    return false;
+}