conductor-bridge 1.0.0

package/dist/utils/file-lock.js

@@ -0,0 +1,117 @@
+/**
+ * File Lock Utility
+ *
+ * Provides cross-platform file locking with retry logic.
+ * Uses proper-lockfile for reliable locking behavior.
+ */
+import { mkdir } from 'fs/promises';
+import { dirname } from 'path';
+const DEFAULT_OPTIONS = {
+    timeout: 10000,
+    retryInterval: 100,
+    maxRetries: 50,
+    stale: 60000,
+};
+// Simple in-memory lock registry for same-process coordination
+const activeLocks = new Map();
+export class FileLockError extends Error {
+    filePath;
+    code;
+    constructor(message, filePath, code) {
+        super(message);
+        this.filePath = filePath;
+        this.code = code;
+        this.name = 'FileLockError';
+    }
+}
+/**
+ * Acquire a lock on a file, execute an operation, then release the lock.
+ *
+ * @param filePath - Path to the file to lock
+ * @param operation - Async operation to perform while holding the lock
+ * @param options - Lock options
+ * @returns Result of the operation
+ *
+ * @example
+ * ```ts
+ * const result = await withFileLock('/path/to/file.json', async () => {
+ *   const data = await readFile('/path/to/file.json', 'utf-8');
+ *   const parsed = JSON.parse(data);
+ *   parsed.count++;
+ *   await writeFile('/path/to/file.json', JSON.stringify(parsed));
+ *   return parsed;
+ * });
+ * ```
+ */
+export async function withFileLock(filePath, operation, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    // Ensure directory exists for lock file
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+    }
+    catch {
+        // Directory might already exist
+    }
+    // Try to acquire lock with retries
+    const lockPath = `${filePath}.lock`;
+    let acquired = false;
+    let attempts = 0;
+    const startTime = Date.now();
+    while (!acquired) {
+        // Check timeout
+        if (Date.now() - startTime > opts.timeout) {
+            throw new FileLockError(`Timeout waiting for lock on ${filePath}`, filePath, 'ETIMEOUT');
+        }
+        // Check max retries
+        if (attempts >= opts.maxRetries) {
+            throw new FileLockError(`Max retries exceeded waiting for lock on ${filePath}`, filePath, 'ETIMEOUT');
+        }
+        // Try to acquire
+        const existingLock = activeLocks.get(lockPath);
+        if (existingLock) {
+            // Check if stale
+            if (Date.now() - existingLock.timestamp > opts.stale) {
+                // Force release stale lock
+                existingLock.release();
+                activeLocks.delete(lockPath);
+            }
+            else {
+                // Wait and retry
+                await sleep(opts.retryInterval);
+                attempts++;
+                continue;
+            }
+        }
+        // Acquire lock
+        const release = () => {
+            activeLocks.delete(lockPath);
+        };
+        activeLocks.set(lockPath, {
+            timestamp: Date.now(),
+            release,
+        });
+        acquired = true;
+    }
+    // Execute operation with lock held
+    try {
+        return await operation();
+    }
+    finally {
+        // Release lock
+        const lock = activeLocks.get(lockPath);
+        if (lock) {
+            lock.release();
+        }
+    }
+}
+/**
+ * Check if a file is currently locked.
+ */
+export function isFileLocked(filePath) {
+    const lockPath = `${filePath}.lock`;
+    return activeLocks.has(lockPath);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/utils/file-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.js","sourceRoot":"","sources":["../../src/utils/file-lock.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Security and Navigation utilities for Conductor Bridge
+ */
+export { atomicWriteFile, fileExists, type AtomicWriteOptions, } from './atomic-write.js';
+export { validatePath, sanitizeFilename, type SafePathResult, } from './safe-path.js';
+export { withFileLock, isFileLocked, FileLockError, type LockOptions, } from './file-lock.js';
+export { readFileWithTimeout, readFileBufferWithTimeout, writeFileWithTimeout, withIOTimeout, FileIOTimeoutError, } from './timed-io.js';
+export { withFallback, withFallbackSync, withRetry, createFallbackWrapper, type FallbackContext, type FallbackOptions, } from './error-handling.js';
+export { RLMNavigator, FileNavigator, MultiFileSearch, PriorBasedFilter, rlmNavigator, SIZE_THRESHOLD_BYTES, DEFAULT_EXTENSIONS, SKIP_DIRS, type NavigationResult, type FileNavigatorOptions, type MultiFileSearchOptions, } from './rlm-navigator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,YAAY,EACZ,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,oBAAoB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,12 @@
+/**
+ * Security and Navigation utilities for Conductor Bridge
+ */
+// Security utilities
+export { atomicWriteFile, fileExists, } from './atomic-write.js';
+export { validatePath, sanitizeFilename, } from './safe-path.js';
+export { withFileLock, isFileLocked, FileLockError, } from './file-lock.js';
+export { readFileWithTimeout, readFileBufferWithTimeout, writeFileWithTimeout, withIOTimeout, FileIOTimeoutError, } from './timed-io.js';
+export { withFallback, withFallbackSync, withRetry, createFallbackWrapper, } from './error-handling.js';
+// RLM Navigator (Zhang, Kraska, Khattab 2025)
+export { RLMNavigator, FileNavigator, MultiFileSearch, PriorBasedFilter, rlmNavigator, SIZE_THRESHOLD_BYTES, DEFAULT_EXTENSIONS, SKIP_DIRS, } from './rlm-navigator.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAqB;AACrB,OAAO,EACL,eAAe,EACf,UAAU,GAEX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,gBAAgB,GAEjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GAEd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,qBAAqB,GAGtB,MAAM,qBAAqB,CAAC;AAE7B,8CAA8C;AAC9C,OAAO,EACL,YAAY,EACZ,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,SAAS,GAIV,MAAM,oBAAoB,CAAC"}

package/dist/utils/rlm-navigator.d.ts

@@ -0,0 +1,160 @@
+/**
+ * RLM Navigator: Program-Environment Paradigm for Large File Navigation
+ *
+ * Implements the Recursive Language Model paradigm from Zhang, Kraska, Khattab (2025):
+ * "Treat long prompts as part of an external environment and allow the LLM
+ * to programmatically examine, decompose, and recursively call itself over snippets"
+ *
+ * Key Principle: Never load large data INTO context. Navigate it FROM context.
+ *
+ * Usage:
+ *     Traditional: [Entire file in context] → "Find X"
+ *     RLM:         [File as external variable] → Write code to find X → Execute → Get result
+ *
+ * Integration with Conductor Bridge:
+ *     - Navigates large spec.md/plan.md files
+ *     - Navigates cognitive state documents
+ *     - Navigates amendment files
+ *     - Supports watcher for large file changes
+ *
+ * Reference: https://arxiv.org/abs/2512.24601
+ */
+export interface NavigationResult {
+    /** Original query/pattern */
+    query: string;
+    /** Matches: [lineNumber, content] */
+    matches: Array<[number, string]>;
+    /** Context snippets around matches */
+    contextSnippets: string[];
+    /** Source file path */
+    filePath?: string;
+    /** Total lines scanned */
+    totalLinesScanned: number;
+    /** Pattern used for search */
+    patternUsed?: string;
+}
+export interface FileNavigatorOptions {
+    /** Maximum matches to return */
+    maxMatches?: number;
+    /** Lines of context around matches */
+    contextLines?: number;
+    /** Case-sensitive search */
+    caseSensitive?: boolean;
+}
+export interface MultiFileSearchOptions extends FileNavigatorOptions {
+    /** File extensions to include */
+    extensions?: string[];
+    /** Maximum total results across all files */
+    maxResults?: number;
+}
+/** Size threshold above which RLM approach should be used (~50K tokens) */
+export declare const SIZE_THRESHOLD_BYTES = 200000;
+/** Default file extensions to search */
+export declare const DEFAULT_EXTENSIONS: string[];
+/** Directories to skip when searching */
+export declare const SKIP_DIRS: Set<string>;
+export declare class FileNavigator {
+    private filePath;
+    private lineCountCache?;
+    constructor(filePath: string);
+    /**
+     * Get total line count (cached).
+     */
+    getLineCount(): Promise<number>;
+    /**
+     * Find pattern in file with surrounding context.
+     */
+    findPattern(pattern: string | RegExp, options?: FileNavigatorOptions): Promise<NavigationResult>;
+    /**
+     * Get specific line range from file.
+     */
+    getLines(start: number, end?: number): Promise<string[]>;
+    /**
+     * Get context around a specific line.
+     */
+    getContext(lineNum: number, window?: number): Promise<string>;
+    /**
+     * Count occurrences of pattern.
+     */
+    countPattern(pattern: string | RegExp, caseSensitive?: boolean): Promise<number>;
+    /**
+     * Stream lines from file.
+     */
+    streamLines(): AsyncGenerator<{
+        lineNum: number;
+        content: string;
+    }>;
+}
+export declare class PriorBasedFilter {
+    private pattern;
+    private priors;
+    constructor(priors: string[]);
+    /**
+     * Filter file using priors.
+     */
+    filterFile(filePath: string, maxMatches?: number): Promise<NavigationResult>;
+    /**
+     * Create filter from natural language query.
+     */
+    static fromQuery(query: string): PriorBasedFilter;
+}
+export declare class MultiFileSearch {
+    private rootDir;
+    private extensions;
+    constructor(rootDir: string, extensions?: string[]);
+    /**
+     * Search across all files matching extensions.
+     */
+    search(pattern: string | RegExp, options?: MultiFileSearchOptions): Promise<NavigationResult[]>;
+    /**
+     * Search using prior-based filtering.
+     */
+    searchWithPriors(priors: string[], maxResults?: number): Promise<NavigationResult[]>;
+    /**
+     * Iterate over files, skipping ignored directories.
+     */
+    private iterFiles;
+}
+export declare class RLMNavigator {
+    private basePath;
+    constructor(basePath?: string);
+    /**
+     * Determine if RLM approach should be used for this file.
+     */
+    shouldUseRLM(filePath: string): Promise<boolean>;
+    /**
+     * Get navigator for a specific file.
+     */
+    navigateFile(filePath: string): FileNavigator;
+    /**
+     * Search across codebase from base path.
+     */
+    searchCodebase(pattern: string | RegExp, extensions?: string[]): Promise<NavigationResult[]>;
+    /**
+     * Navigate a cognitive state document.
+     */
+    findInCognitiveState(statePath: string, query: string): Promise<NavigationResult>;
+    /**
+     * Navigate a Conductor markdown file (spec.md, plan.md, state.md).
+     */
+    findInConductorFile(filePath: string, pattern: string, options?: FileNavigatorOptions): Promise<NavigationResult>;
+    /**
+     * Analyze a log file without loading into context.
+     */
+    analyzeLog(logPath: string, errorOnly?: boolean): Promise<{
+        errors: {
+            count: number;
+            samples: string[];
+        };
+        warnings: {
+            count: number;
+            samples: string[];
+        };
+        info: {
+            count: number;
+            samples: string[];
+        };
+    }>;
+}
+export declare const rlmNavigator: RLMNavigator;
+//# sourceMappingURL=rlm-navigator.d.ts.map

package/dist/utils/rlm-navigator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rlm-navigator.d.ts","sourceRoot":"","sources":["../../src/utils/rlm-navigator.ts"],"names":[],"mappings":"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"}

package/dist/utils/rlm-navigator.js

@@ -0,0 +1,368 @@
+/**
+ * RLM Navigator: Program-Environment Paradigm for Large File Navigation
+ *
+ * Implements the Recursive Language Model paradigm from Zhang, Kraska, Khattab (2025):
+ * "Treat long prompts as part of an external environment and allow the LLM
+ * to programmatically examine, decompose, and recursively call itself over snippets"
+ *
+ * Key Principle: Never load large data INTO context. Navigate it FROM context.
+ *
+ * Usage:
+ *     Traditional: [Entire file in context] → "Find X"
+ *     RLM:         [File as external variable] → Write code to find X → Execute → Get result
+ *
+ * Integration with Conductor Bridge:
+ *     - Navigates large spec.md/plan.md files
+ *     - Navigates cognitive state documents
+ *     - Navigates amendment files
+ *     - Supports watcher for large file changes
+ *
+ * Reference: https://arxiv.org/abs/2512.24601
+ */
+import { createReadStream } from 'fs';
+import { stat, readdir } from 'fs/promises';
+import { createInterface } from 'readline';
+import { join, extname } from 'path';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Size threshold above which RLM approach should be used (~50K tokens) */
+export const SIZE_THRESHOLD_BYTES = 200_000;
+/** Default file extensions to search */
+export const DEFAULT_EXTENSIONS = ['.ts', '.js', '.md', '.json', '.txt'];
+/** Directories to skip when searching */
+export const SKIP_DIRS = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.cache',
+]);
+// ============================================================================
+// FileNavigator: Single File Navigation
+// ============================================================================
+export class FileNavigator {
+    filePath;
+    lineCountCache;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /**
+     * Get total line count (cached).
+     */
+    async getLineCount() {
+        if (this.lineCountCache !== undefined) {
+            return this.lineCountCache;
+        }
+        let count = 0;
+        for await (const _ of this.streamLines()) {
+            count++;
+        }
+        this.lineCountCache = count;
+        return count;
+    }
+    /**
+     * Find pattern in file with surrounding context.
+     */
+    async findPattern(pattern, options = {}) {
+        const { maxMatches = 100, contextLines = 3, caseSensitive = false, } = options;
+        const regex = pattern instanceof RegExp
+            ? pattern
+            : new RegExp(pattern, caseSensitive ? '' : 'i');
+        const matches = [];
+        const contextSnippets = [];
+        const allLines = [];
+        let totalLines = 0;
+        // First pass: collect all lines and find matches
+        for await (const { lineNum, content } of this.streamLines()) {
+            allLines.push(content);
+            totalLines = lineNum;
+            if (regex.test(content) && matches.length < maxMatches) {
+                matches.push([lineNum, content.trim()]);
+            }
+        }
+        // Second pass: get context for matches
+        for (const [lineNum] of matches) {
+            const start = Math.max(0, lineNum - contextLines - 1);
+            const end = Math.min(allLines.length, lineNum + contextLines);
+            const context = allLines.slice(start, end).join('\n');
+            contextSnippets.push(context);
+        }
+        return {
+            query: pattern.toString(),
+            matches,
+            contextSnippets,
+            filePath: this.filePath,
+            totalLinesScanned: totalLines,
+            patternUsed: regex.source,
+        };
+    }
+    /**
+     * Get specific line range from file.
+     */
+    async getLines(start, end) {
+        const targetEnd = end ?? start;
+        const lines = [];
+        for await (const { lineNum, content } of this.streamLines()) {
+            if (lineNum >= start && lineNum <= targetEnd) {
+                lines.push(content);
+            }
+            if (lineNum > targetEnd) {
+                break;
+            }
+        }
+        return lines;
+    }
+    /**
+     * Get context around a specific line.
+     */
+    async getContext(lineNum, window = 5) {
+        const start = Math.max(1, lineNum - window);
+        const end = lineNum + window;
+        const lines = await this.getLines(start, end);
+        return lines.join('\n');
+    }
+    /**
+     * Count occurrences of pattern.
+     */
+    async countPattern(pattern, caseSensitive = false) {
+        const regex = pattern instanceof RegExp
+            ? pattern
+            : new RegExp(pattern, caseSensitive ? 'g' : 'gi');
+        let count = 0;
+        for await (const { content } of this.streamLines()) {
+            const matches = content.match(regex);
+            if (matches) {
+                count += matches.length;
+            }
+        }
+        return count;
+    }
+    /**
+     * Stream lines from file.
+     */
+    async *streamLines() {
+        const rl = createInterface({
+            input: createReadStream(this.filePath, { encoding: 'utf-8' }),
+            crlfDelay: Infinity,
+        });
+        let lineNum = 0;
+        for await (const line of rl) {
+            lineNum++;
+            yield { lineNum, content: line };
+        }
+    }
+}
+// ============================================================================
+// PriorBasedFilter: Filter Using Expectations
+// ============================================================================
+export class PriorBasedFilter {
+    pattern;
+    priors;
+    constructor(priors) {
+        this.priors = priors;
+        const escaped = priors.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        this.pattern = new RegExp(escaped.join('|'), 'i');
+    }
+    /**
+     * Filter file using priors.
+     */
+    async filterFile(filePath, maxMatches = 100) {
+        const nav = new FileNavigator(filePath);
+        const matches = [];
+        let totalLines = 0;
+        for await (const { lineNum, content } of nav.streamLines()) {
+            totalLines = lineNum;
+            if (this.pattern.test(content) && matches.length < maxMatches) {
+                matches.push([lineNum, content.trim()]);
+            }
+        }
+        return {
+            query: this.priors.join('|'),
+            matches,
+            contextSnippets: [],
+            filePath,
+            totalLinesScanned: totalLines,
+            patternUsed: this.pattern.source,
+        };
+    }
+    /**
+     * Create filter from natural language query.
+     */
+    static fromQuery(query) {
+        // Extract words longer than 3 chars as potential priors
+        const words = query.toLowerCase().match(/\b\w{4,}\b/g) || [];
+        // Remove common stop words
+        const stopWords = new Set([
+            'what',
+            'where',
+            'when',
+            'which',
+            'that',
+            'this',
+            'have',
+            'from',
+            'with',
+            'about',
+        ]);
+        const priors = words.filter((w) => !stopWords.has(w));
+        return new PriorBasedFilter(priors);
+    }
+}
+// ============================================================================
+// MultiFileSearch: Search Across Multiple Files
+// ============================================================================
+export class MultiFileSearch {
+    rootDir;
+    extensions;
+    constructor(rootDir, extensions) {
+        this.rootDir = rootDir;
+        this.extensions = extensions ?? DEFAULT_EXTENSIONS;
+    }
+    /**
+     * Search across all files matching extensions.
+     */
+    async search(pattern, options = {}) {
+        const { maxResults = 100, ...fileOptions } = options;
+        const results = [];
+        let totalMatches = 0;
+        for await (const filePath of this.iterFiles()) {
+            if (totalMatches >= maxResults) {
+                break;
+            }
+            const nav = new FileNavigator(filePath);
+            const result = await nav.findPattern(pattern, {
+                ...fileOptions,
+                maxMatches: maxResults - totalMatches,
+            });
+            if (result.matches.length > 0) {
+                results.push(result);
+                totalMatches += result.matches.length;
+            }
+        }
+        return results;
+    }
+    /**
+     * Search using prior-based filtering.
+     */
+    async searchWithPriors(priors, maxResults = 100) {
+        const filter = new PriorBasedFilter(priors);
+        const results = [];
+        let totalMatches = 0;
+        for await (const filePath of this.iterFiles()) {
+            if (totalMatches >= maxResults) {
+                break;
+            }
+            const result = await filter.filterFile(filePath, maxResults - totalMatches);
+            if (result.matches.length > 0) {
+                results.push(result);
+                totalMatches += result.matches.length;
+            }
+        }
+        return results;
+    }
+    /**
+     * Iterate over files, skipping ignored directories.
+     */
+    async *iterFiles(dir) {
+        const currentDir = dir ?? this.rootDir;
+        try {
+            const entries = await readdir(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = join(currentDir, entry.name);
+                if (entry.isDirectory()) {
+                    if (!SKIP_DIRS.has(entry.name)) {
+                        yield* this.iterFiles(fullPath);
+                    }
+                }
+                else if (entry.isFile()) {
+                    const ext = extname(entry.name);
+                    if (this.extensions.includes(ext)) {
+                        yield fullPath;
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip unreadable directories
+        }
+    }
+}
+// ============================================================================
+// RLMNavigator: High-Level Navigation Interface
+// ============================================================================
+export class RLMNavigator {
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath ?? process.cwd();
+    }
+    /**
+     * Determine if RLM approach should be used for this file.
+     */
+    async shouldUseRLM(filePath) {
+        try {
+            const stats = await stat(filePath);
+            return stats.size > SIZE_THRESHOLD_BYTES;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get navigator for a specific file.
+     */
+    navigateFile(filePath) {
+        return new FileNavigator(filePath);
+    }
+    /**
+     * Search across codebase from base path.
+     */
+    async searchCodebase(pattern, extensions) {
+        const searcher = new MultiFileSearch(this.basePath, extensions);
+        return searcher.search(pattern);
+    }
+    /**
+     * Navigate a cognitive state document.
+     */
+    async findInCognitiveState(statePath, query) {
+        const filter = PriorBasedFilter.fromQuery(query);
+        return filter.filterFile(statePath);
+    }
+    /**
+     * Navigate a Conductor markdown file (spec.md, plan.md, state.md).
+     */
+    async findInConductorFile(filePath, pattern, options) {
+        const nav = new FileNavigator(filePath);
+        return nav.findPattern(pattern, options);
+    }
+    /**
+     * Analyze a log file without loading into context.
+     */
+    async analyzeLog(logPath, errorOnly = false) {
+        const nav = new FileNavigator(logPath);
+        const patterns = {
+            errors: '(ERROR|FATAL|Exception|Traceback)',
+            warnings: '(WARNING|WARN)',
+            info: '(INFO)',
+        };
+        const results = {};
+        for (const [key, pattern] of Object.entries(patterns)) {
+            if (errorOnly && !['errors', 'warnings'].includes(key)) {
+                results[key] = { count: 0, samples: [] };
+                continue;
+            }
+            const result = await nav.findPattern(pattern, { maxMatches: 50 });
+            results[key] = {
+                count: result.matches.length,
+                samples: result.matches.slice(0, 5).map(([, content]) => content.slice(0, 100)),
+            };
+        }
+        return results;
+    }
+}
+// ============================================================================
+// Convenience Exports
+// ============================================================================
+export const rlmNavigator = new RLMNavigator();
+//# sourceMappingURL=rlm-navigator.js.map