byterover-cli 0.4.1 → 1.0.1

package/dist/utils/crash-log.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Crash Log - Re-exports from unified process-logger.
+ *
+ * @deprecated Use crashLog from process-logger.ts directly.
+ * This file is kept for backwards compatibility.
+ */
+/**
+ * @deprecated Use crashLog from process-logger.ts
+ */
+export declare function writeCrashLog(error: Error | string, context?: string): Promise<string>;
+/**
+ * @deprecated Use getSessionLogPath from process-logger.ts
+ */
+export declare function getLogsDir(): string;

package/dist/utils/crash-log.js

@@ -0,0 +1,19 @@
+/**
+ * Crash Log - Re-exports from unified process-logger.
+ *
+ * @deprecated Use crashLog from process-logger.ts directly.
+ * This file is kept for backwards compatibility.
+ */
+import { crashLog, getSessionLogPath } from './process-logger.js';
+/**
+ * @deprecated Use crashLog from process-logger.ts
+ */
+export async function writeCrashLog(error, context) {
+    return crashLog(error, context);
+}
+/**
+ * @deprecated Use getSessionLogPath from process-logger.ts
+ */
+export function getLogsDir() {
+    return getSessionLogPath();
+}

package/dist/utils/file-helpers.d.ts

@@ -19,6 +19,20 @@ export declare function clearDirectory(dirPath: string): Promise<number>;
  * @returns The sanitized folder path
  */
 export declare function sanitizeFolderName(folderName: string): string;
+/**
+ * Converts a string to lowercase snake_case for file/folder naming.
+ * Replaces spaces and special characters with underscores, converts to lowercase.
+ * @param name - The name to convert
+ * @returns The snake_case version of the name
+ *
+ * @example
+ * ```ts
+ * toSnakeCase('Best Practices') // => 'best_practices'
+ * toSnakeCase('Error-Handling') // => 'error_handling'
+ * toSnakeCase('QuickSort Optimizations') // => 'quicksort_optimizations'
+ * ```
+ */
+export declare function toSnakeCase(name: string): string;
 /**
  * Lists all immediate children (files and directories) of the given directory,
  * and, for each child folder, shows its own immediate children.

package/dist/utils/file-helpers.js

@@ -52,6 +52,27 @@ export async function clearDirectory(dirPath) {
 export function sanitizeFolderName(folderName) {
     return folderName.replaceAll(/[^\w\-./]/g, '-');
 }
+/**
+ * Converts a string to lowercase snake_case for file/folder naming.
+ * Replaces spaces and special characters with underscores, converts to lowercase.
+ * @param name - The name to convert
+ * @returns The snake_case version of the name
+ *
+ * @example
+ * ```ts
+ * toSnakeCase('Best Practices') // => 'best_practices'
+ * toSnakeCase('Error-Handling') // => 'error_handling'
+ * toSnakeCase('QuickSort Optimizations') // => 'quicksort_optimizations'
+ * ```
+ */
+export function toSnakeCase(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replaceAll(/[^\w]+/g, '_')
+        .replaceAll(/_{2,}/g, '_')
+        .replaceAll(/^_|_$/g, '');
+}
 /**
  * Lists all immediate children (files and directories) of the given directory,
  * and, for each child folder, shows its own immediate children.

package/dist/utils/global-logs-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns the global logs directory path following platform conventions:
+ * - Windows: %LOCALAPPDATA%/brv/logs
+ * - macOS: ~/Library/Logs/brv
+ * - Linux: $XDG_STATE_HOME/brv/logs (defaults to ~/.local/state/brv/logs)
+ *
+ * Falls back to temp directory if any system call fails.
+ *
+ * @returns Absolute path to the global logs directory
+ */
+export declare function getGlobalLogsDir(): string;

package/dist/utils/global-logs-path.js

@@ -0,0 +1,37 @@
+import { homedir, platform, tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Returns the global logs directory path following platform conventions:
+ * - Windows: %LOCALAPPDATA%/brv/logs
+ * - macOS: ~/Library/Logs/brv
+ * - Linux: $XDG_STATE_HOME/brv/logs (defaults to ~/.local/state/brv/logs)
+ *
+ * Falls back to temp directory if any system call fails.
+ *
+ * @returns Absolute path to the global logs directory
+ */
+export function getGlobalLogsDir() {
+    try {
+        const currentPlatform = platform();
+        if (currentPlatform === 'win32') {
+            const localAppData = process.env.LOCALAPPDATA;
+            if (localAppData) {
+                return join(localAppData, 'brv', 'logs');
+            }
+            return join(homedir(), 'AppData', 'Local', 'brv', 'logs');
+        }
+        if (currentPlatform === 'darwin') {
+            return join(homedir(), 'Library', 'Logs', 'brv');
+        }
+        // Linux: XDG_STATE_HOME/brv/logs
+        const xdgStateHome = process.env.XDG_STATE_HOME;
+        if (xdgStateHome) {
+            return join(xdgStateHome, 'brv', 'logs');
+        }
+        return join(homedir(), '.local', 'state', 'brv', 'logs');
+    }
+    catch {
+        // Fallback to temp directory if any system call fails
+        return join(tmpdir(), 'brv', 'logs');
+    }
+}

package/dist/utils/process-logger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Unified Process Logger - Single log file per session.
+ *
+ * Logs are stored following platform conventions:
+ * - Windows: %LOCALAPPDATA%/brv/logs/brv-{timestamp}.log
+ * - macOS: ~/Library/Logs/brv/brv-{timestamp}.log
+ * - Linux: $XDG_STATE_HOME/brv/logs/brv-{timestamp}.log
+ *
+ * Each session creates a new log file with timestamp.
+ */
+/**
+ * Initialize session log - creates a new log file for this session.
+ * Should be called once when the main process starts.
+ */
+export declare function initSessionLog(): void;
+/**
+ * Write a log entry to the log file.
+ * Uses synchronous append for reliability in process shutdown scenarios.
+ */
+export declare function processLog(message: string): void;
+/**
+ * Log with [Transport] prefix.
+ */
+export declare function transportLog(message: string): void;
+/**
+ * Log with [Agent] prefix.
+ */
+export declare function agentLog(message: string): void;
+/**
+ * Log with [ProcessManager] prefix.
+ */
+export declare function processManagerLog(message: string): void;
+/**
+ * Log a transport event (for TUI monitoring).
+ */
+export declare function eventLog(eventName: string, data?: unknown): void;
+/**
+ * Log an error with full details.
+ */
+export declare function errorLog(error: Error | string, context?: string): void;
+/**
+ * Log a crash with full environment details.
+ * Everything goes to the session log file.
+ * Never throws - always returns a log path (even if logging failed).
+ *
+ * @returns The path to the log file (for user feedback)
+ */
+export declare function crashLog(error: Error | string, contextStr?: string): string;
+/**
+ * Get the path to the current session's log file.
+ * Never throws - returns fallback path if session path unavailable.
+ */
+export declare function getSessionLogPath(): string;

package/dist/utils/process-logger.js

@@ -0,0 +1,253 @@
+/**
+ * Unified Process Logger - Single log file per session.
+ *
+ * Logs are stored following platform conventions:
+ * - Windows: %LOCALAPPDATA%/brv/logs/brv-{timestamp}.log
+ * - macOS: ~/Library/Logs/brv/brv-{timestamp}.log
+ * - Linux: $XDG_STATE_HOME/brv/logs/brv-{timestamp}.log
+ *
+ * Each session creates a new log file with timestamp.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getGlobalLogsDir } from './global-logs-path.js';
+/** Current session's log file path (set on init) */
+let sessionLogPath;
+/**
+ * Get the logs directory path.
+ */
+function getLogsDir() {
+    return getGlobalLogsDir();
+}
+/**
+ * Ensure logs directory exists.
+ * Silently ignores errors to prevent crashes.
+ */
+function ensureLogDir() {
+    try {
+        const logsDir = getLogsDir();
+        if (!existsSync(logsDir)) {
+            mkdirSync(logsDir, { recursive: true });
+        }
+    }
+    catch {
+        // Silently ignore - directory creation may fail due to permissions
+        // Logging will fail gracefully later when trying to write
+    }
+}
+/** Max age for log files in milliseconds (30 days) */
+const LOG_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Clean up log files older than 30 days.
+ * Runs silently - errors are ignored to not affect the main process.
+ */
+function cleanupOldLogs() {
+    try {
+        const logsDir = getLogsDir();
+        if (!existsSync(logsDir))
+            return;
+        const now = Date.now();
+        const files = readdirSync(logsDir);
+        for (const file of files) {
+            if (!file.endsWith('.log'))
+                continue;
+            const filePath = join(logsDir, file);
+            const stats = statSync(filePath);
+            const age = now - stats.mtimeMs;
+            if (age > LOG_MAX_AGE_MS) {
+                unlinkSync(filePath);
+            }
+        }
+    }
+    catch {
+        // Silently ignore - don't crash the process
+    }
+}
+/**
+ * Format timestamp for log entries.
+ */
+function formatTimestamp() {
+    const now = new Date();
+    return now.toISOString().replace('T', ' ').slice(0, 23);
+}
+/**
+ * Generate session log filename with timestamp.
+ */
+function generateSessionLogFilename() {
+    const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').slice(0, 19);
+    return `brv-${timestamp}.log`;
+}
+/**
+ * Get current session's log file path.
+ * Uses BRV_SESSION_LOG env var if set (for child processes),
+ * otherwise creates new session file.
+ */
+function getLogPath() {
+    if (!sessionLogPath) {
+        // Check if parent process set the log path
+        const envLogPath = process.env.BRV_SESSION_LOG;
+        if (envLogPath) {
+            sessionLogPath = envLogPath;
+        }
+        else {
+            // Try to create log directory, but don't crash if it fails
+            // getLogsDir() has its own fallback to tmpdir() via getGlobalLogsDir()
+            try {
+                ensureLogDir();
+            }
+            catch {
+                // Directory creation failed - subsequent writes will also fail silently
+                // This prevents crash when getSessionLogPath() is called from process-manager
+            }
+            sessionLogPath = join(getLogsDir(), generateSessionLogFilename());
+        }
+    }
+    return sessionLogPath;
+}
+/**
+ * Initialize session log - creates a new log file for this session.
+ * Should be called once when the main process starts.
+ */
+export function initSessionLog() {
+    if (sessionLogPath)
+        return;
+    try {
+        ensureLogDir();
+        cleanupOldLogs();
+        sessionLogPath = join(getLogsDir(), generateSessionLogFilename());
+        const timestamp = formatTimestamp();
+        const header = [
+            '='.repeat(70),
+            `BRV Session Log - Started: ${timestamp}`,
+            `CWD: ${process.cwd()}`,
+            `Node: ${process.version} | Platform: ${process.platform} | PID: ${process.pid}`,
+            '='.repeat(70),
+            '',
+        ].join('\n');
+        writeFileSync(sessionLogPath, header);
+    }
+    catch {
+        // Silently ignore - don't crash the process
+    }
+}
+/**
+ * Write a log entry to the log file.
+ * Uses synchronous append for reliability in process shutdown scenarios.
+ */
+export function processLog(message) {
+    try {
+        ensureLogDir();
+        const timestamp = formatTimestamp();
+        const logLine = `${timestamp} ${message}\n`;
+        appendFileSync(getLogPath(), logLine);
+    }
+    catch {
+        // Silently ignore log failures - don't crash the process
+    }
+}
+/**
+ * Log with [Transport] prefix.
+ */
+export function transportLog(message) {
+    processLog(`[Transport] ${message}`);
+}
+/**
+ * Log with [Agent] prefix.
+ */
+export function agentLog(message) {
+    processLog(`[Agent] ${message}`);
+}
+/**
+ * Log with [ProcessManager] prefix.
+ */
+export function processManagerLog(message) {
+    processLog(`[ProcessManager] ${message}`);
+}
+/**
+ * Log a transport event (for TUI monitoring).
+ */
+export function eventLog(eventName, data) {
+    const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+    processLog(`[Event] ${eventName}${dataStr}`);
+}
+/**
+ * Log an error with full details.
+ */
+export function errorLog(error, context) {
+    const errorMessage = error instanceof Error ? error.message : error;
+    const errorStack = error instanceof Error ? error.stack : undefined;
+    const contextStr = context ? ` (${context})` : '';
+    processLog(`[ERROR]${contextStr} ${errorMessage}`);
+    if (errorStack) {
+        const indentedStack = errorStack
+            .split('\n')
+            .slice(1)
+            .map((line) => `         ${line}`)
+            .join('\n');
+        processLog(indentedStack);
+    }
+}
+/**
+ * Log a crash with full environment details.
+ * Everything goes to the session log file.
+ * Never throws - always returns a log path (even if logging failed).
+ *
+ * @returns The path to the log file (for user feedback)
+ */
+export function crashLog(error, contextStr = 'Unknown') {
+    let logPath;
+    try {
+        const errorMessage = error instanceof Error ? error.message : error;
+        const errorStack = error instanceof Error ? error.stack : undefined;
+        const timestamp = formatTimestamp();
+        logPath = getLogPath();
+        ensureLogDir();
+        const crashContent = [
+            '',
+            '!'.repeat(70),
+            `CRASH at ${timestamp}`,
+            '!'.repeat(70),
+            '',
+            `Context: ${contextStr}`,
+            `Message: ${errorMessage}`,
+            '',
+            'Stack Trace:',
+            errorStack ?? '(No stack trace available)',
+            '',
+            'Environment:',
+            `  Node.js: ${process.version}`,
+            `  Platform: ${process.platform}`,
+            `  Arch: ${process.arch}`,
+            `  CWD: ${process.cwd()}`,
+            `  PID: ${process.pid}`,
+            '',
+            'Memory Usage:',
+            JSON.stringify(process.memoryUsage(), null, 2)
+                .split('\n')
+                .map((line) => `  ${line}`)
+                .join('\n'),
+            '',
+            '!'.repeat(70),
+            '',
+        ].join('\n');
+        appendFileSync(logPath, crashContent);
+    }
+    catch {
+        // If we can't write or get path, return a fallback path for user feedback
+        logPath = logPath || join(getGlobalLogsDir(), 'brv-crash.log');
+    }
+    return logPath;
+}
+/**
+ * Get the path to the current session's log file.
+ * Never throws - returns fallback path if session path unavailable.
+ */
+export function getSessionLogPath() {
+    try {
+        return getLogPath();
+    }
+    catch {
+        // Fallback to a predictable path if getLogPath fails
+        return join(getGlobalLogsDir(), 'brv-session.log');
+    }
+}

package/dist/utils/sandbox-detector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Detects if the current process is running in a sandboxed environment
+ * (e.g., Cursor AI agent, VSCode extension, Claude Code, Codex, etc.)
+ *
+ * Sandboxed environments typically have restricted network access and
+ * may set specific environment variables or have characteristic error patterns.
+ */
+export declare function isSandboxEnvironment(): boolean;
+/**
+ * Detects if an error is specifically a sandbox network restriction error.
+ *
+ * Sandbox network errors have characteristic patterns:
+ * - WebSocket connection failures with "network" or "websocket error"
+ * - XHR poll errors (Socket.IO fallback blocked)
+ * - Connection refused errors that occur immediately (sandbox blocks before connection)
+ *
+ * This is more specific than general network errors which might be:
+ * - Actual network connectivity issues
+ * - Firewall blocks
+ * - Server not running
+ * - CORS origin errors (though with CORS origin = '*', this shouldn't happen)
+ *
+ * Note: With CORS origin configured as '*', CORS errors are impossible.
+ * When connection fails in sandbox, it's almost certainly due to network permission,
+ * not origin restrictions.
+ */
+export declare function isSandboxNetworkError(error: Error | string): boolean;
+/**
+ * Gets a user-friendly description of the detected sandbox environment.
+ */
+export declare function getSandboxEnvironmentName(): string;

package/dist/utils/sandbox-detector.js

@@ -0,0 +1,122 @@
+/**
+ * Detects if the current process is running in a sandboxed environment
+ * (e.g., Cursor AI agent, VSCode extension, Claude Code, Codex, etc.)
+ *
+ * Sandboxed environments typically have restricted network access and
+ * may set specific environment variables or have characteristic error patterns.
+ */
+export function isSandboxEnvironment() {
+    // Check for IDE-specific environment variables
+    const { env } = process;
+    // Cursor IDE
+    if (env.CURSOR_AGENT || env.CURSOR_SESSION_ID) {
+        return true;
+    }
+    // VS Code / GitHub Copilot
+    if (env.VSCODE_INJECTION || env.VSCODE_PID || env.VSCODE_IPC_HOOK) {
+        return true;
+    }
+    // Claude Code
+    if (env.CLAUDE_AGENT || env.CLAUDE_SESSION) {
+        return true;
+    }
+    // Codex
+    if (env.CODEX_AGENT || env.CODEX_SESSION) {
+        return true;
+    }
+    // Windsurf
+    if (env.WINDSURF_AGENT || env.WINDSURF_SESSION) {
+        return true;
+    }
+    // Check for common sandbox indicators
+    // Sandboxed terminals often have restricted stdin/stdout
+    if (!process.stdin.isTTY && !process.stdout.isTTY) {
+        // This alone isn't enough, but combined with error patterns it helps
+        // We'll rely more on error message patterns for detection
+    }
+    return false;
+}
+/**
+ * Detects if an error is specifically a sandbox network restriction error.
+ *
+ * Sandbox network errors have characteristic patterns:
+ * - WebSocket connection failures with "network" or "websocket error"
+ * - XHR poll errors (Socket.IO fallback blocked)
+ * - Connection refused errors that occur immediately (sandbox blocks before connection)
+ *
+ * This is more specific than general network errors which might be:
+ * - Actual network connectivity issues
+ * - Firewall blocks
+ * - Server not running
+ * - CORS origin errors (though with CORS origin = '*', this shouldn't happen)
+ *
+ * Note: With CORS origin configured as '*', CORS errors are impossible.
+ * When connection fails in sandbox, it's almost certainly due to network permission,
+ * not origin restrictions.
+ */
+export function isSandboxNetworkError(error) {
+    const errorMessage = typeof error === 'string' ? error : error.message;
+    const lowerMessage = errorMessage.toLowerCase();
+    // First, check if it's a CORS/origin error (unlikely with origin = '*', but check anyway)
+    const isCorsError = lowerMessage.includes('cors') ||
+        lowerMessage.includes('origin') ||
+        (lowerMessage.includes('forbidden') && lowerMessage.includes('origin'));
+    // If it's a CORS error, it's NOT a sandbox network permission error
+    // (though with origin = '*', CORS errors shouldn't occur)
+    if (isCorsError) {
+        return false;
+    }
+    // Specific sandbox network permission error patterns
+    const sandboxPatterns = [
+        // WebSocket errors that indicate sandbox blocking
+        'websocket error',
+        'xhr poll error',
+        // Network errors that occur immediately (sandbox blocks before connection)
+        'network',
+        // Connection refused that happens immediately (sandbox blocks)
+        'econnrefused',
+    ];
+    // Check if error matches sandbox patterns
+    const matchesSandboxPattern = sandboxPatterns.some((pattern) => lowerMessage.includes(pattern));
+    // Additional check: if it's a connection error but instance is likely running
+    // (we can't know for sure, but sandbox errors are usually immediate failures)
+    const isConnectionError = lowerMessage.includes('connection') || lowerMessage.includes('connect');
+    // Only consider it a sandbox network permission error if:
+    // 1. Matches sandbox patterns AND
+    // 2. Is a connection-related error AND
+    // 3. We're in a sandbox environment (or error pattern strongly suggests it)
+    // 4. NOT a CORS error (already checked above)
+    if (matchesSandboxPattern && isConnectionError) {
+        // Prefer environment detection, but if error pattern is very specific, trust it
+        if (isSandboxEnvironment()) {
+            return true;
+        }
+        // Very specific sandbox error patterns that we can trust even without env detection
+        if (lowerMessage.includes('websocket error') || lowerMessage.includes('xhr poll error')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Gets a user-friendly description of the detected sandbox environment.
+ */
+export function getSandboxEnvironmentName() {
+    const { env } = process;
+    if (env.CURSOR_AGENT || env.CURSOR_SESSION_ID) {
+        return 'Cursor';
+    }
+    if (env.VSCODE_INJECTION || env.VSCODE_PID || env.VSCODE_IPC_HOOK) {
+        return 'VS Code / GitHub Copilot';
+    }
+    if (env.CLAUDE_AGENT || env.CLAUDE_SESSION) {
+        return 'Claude Code';
+    }
+    if (env.CODEX_AGENT || env.CODEX_SESSION) {
+        return 'Codex';
+    }
+    if (env.WINDSURF_AGENT || env.WINDSURF_SESSION) {
+        return 'Windsurf';
+    }
+    return 'IDE sandbox';
+}